COLLABORATING ON GIT AND GITHUB

Anne Gentle

FOR DOCUMENTATION

Questions at the end, but you can always ask me anything:

documenting 20 cloud servicesacross 130 GitHub repositorieswith 728 contributors in 4 years

@annegentle, #CIDMOnlineanne.gentle@rackspace.comwww.justwriteclick.com

GIT AND GITHUB

• 2005 born after spectacular Linux tooling failure

• Social web, leads to social coding

• Git is for command line, GitHub is the web interface

• Cross-platform tooling - Windows, Mac, Linux

• Merge files rather than a “lock and checkout” model

• Non-linear branching model

GITHUB VOCABULARY

Repository

Collection of stored code

Organization

Collection of repositories

Fork

Copy repository, copy of repository

Issue

Defects, tasks, or feature requests

Pull Request

Comparison of edits to see if team wants to accept changes

Commit

Point in time snapshot of repository with changes

Branch

Indicator of divergence from base

• Command line tool

• Only place for all the commands

GIT

• Web interface for git repositories

• http://github.com• Comments, reviews, emojis

GITHUB

LET’S TALK ABOUTPAIN POINTS

“Meet the deadline.”

“What can we get rid of before the deadline? I know…”

“Let’s do Agile, but…”

“Devs rule - docs drool.”

flickr :cobalt123

WRITING IN ISOLATION

flickr :mtischendorf

COLLABORATE WHERE USERS ARE• Curate the audience

• Write with and for the audience

• Reward the audience

I NEED A WRITER1. Sacrifice your first-born for headcount

and job description.2. Come up with a pay scale.3. Get a handful of resumes that don’t

meet the requirements.4. Cry.

flickr :eclecticechoes

Ensure that contributors are valued and rewarded!

• Sense of belonging• Pay it forward (reciprocity)• Effective, time-saving, user support• Reputation, recruiting

MOTIVATIONS

flickr :seeminglee

LET’S CURATEAuthors

ProcessesTools

MindsetsAttitudes

Jobs

flickr :roswellsgirl

TREAT DOCS LIKE CODE

flickr :roswellsgirl

LONGTAIL CONTRIBUTIONS• Rise of the niche

• Finding like-minded people interested in your content

• Dark corners of knowledge gap are filled with docs

THE DOCS SUCKIn what way?

Which page?

How can I get it not to suck?

flickr :heidiandmatt

DOC ISSUES TRACKING• Tasks, outright errors, and

feature requests

• I’ll triage the issue and guide you in fixing it, issue reporter

• https://guides.github.com/features/issues/

WRITERS NEVER GET REVIEWSDocumentation system so separate from code system that technical reviews are through email

or

*gasp*

frozen-in-time PDF files

flickr :elkaypics

REVIEWERS FIX DOCS“This is wrong, here’s how to fix it.”

• Working in the same collaboration tools as technical people gives better reviews

• We can merge as many as 50 patches per day; running four automated tests per patch and requiring two humans to check the patch and click in order to publish

UNFAIR TREATMENT

Docs ghetto

flickr :mtischendorf

VALUE PROPOSITIONWriter contributions, when treated like code, are valued equally with developer code

WHITE COAT TOOLSClosely guarded secrets of proprietary toolchains with expensive per-seat licenses.

or

Secret developer workflows are mysterious to writers.

flickr :darthnick

BEAUTIFUL DOCS

• Widely accepted tooling built in the open so we make it work for us and for devs (readthedocs.org)

• Simple markup

• Flat file builds

• We can patch and log issues against the tooling

ONLY DEV TEAMS GET CI/CD

Deploying containers and micro services oh my.

Docs, use some horrifyingly slow proprietary tool, kthnxbai.

flickr : photohome_uk

CI/CD FOR ALL

• Docs can be published automatically after reviewers merge them

• Docs can have simple tests to ensure quality and that you “don’t break the build.”

• Scrape the code to build more helpful docs (especially reference)

• https://opensource.com/business/15/7/continuous-integration-and-continuous-delivery-documentation

flickr :pedrovezini

DRAFTS FOR REVIEWS

• Static site generation from a branch or fork

• Enables publishing both drafts and final output

flickr :denverjeffrey

WHAT PAIRS WELL WITH GITHUB?• Simple markup: Markdown, Middleman, RST• GitHub Pages: http://pages.github.com • Static site generators: https://staticsitegenerators.net/• Well-documented style guide and contributor guide• Open licensing: Creative Commons• PenFlip is “GitHub for Writers”• Borrowing development techniques

WHO USES GIT AND GITHUB FOR WRITING?

• O’Reilly Media for book publishing

• GitHub uses GitHub to document GitHub

• OpenStack uses open source Git

• Rackspace Cloud documentation uses GitHub

WHAT ARE SOME DIFFICULTIES?

• Scope and scale questions• Official-ness• Identity• Naming

flickr :lamont_cranston

GITHUB BENEFITS• Collaborate where users are• Motivate more contributors; track and reward contributions• Version control; release management; CI/CD• Track issues for distributed assignments and improved quality• Create a quality bar for entry• Enable fine-grained reviews and attract more reviewers• Automate tedious tasks• Coach writing skills and build better writers out of subject matter experts• Review incoming contributions; establish specialty teams for reviews• Build reputation and street credibility with metrics

flickr :lnx

DISTRIBUTED ASSIGNMENTS

You shall not pass… • test style guide• test syntax • test build

QUALITY GATE

flickr :davebloggs007

END THE TEDIUM ENABLE THE ROBOTS

• Build the docs and publish them to drafts or staging area

• Docs are always available for reviews

flickr :hddod

COACH BETTER WRITING• Become the experts and

consultants while enabling others to improve their writing

• The people with the knowledge can become better writers and learn more empathy by writing for the users

flickr : philgaldys

CREATE TEAMS

• We now divide the work by deliverable: user guides, install guides, configuration guides

• We scrape the code as often as we can to deliver continuously

flickr :mortimer

BUILD A REPUTATION• Measure quality and

quantity

• Count contributions and improvements

• Compare over time; benchmark and reward

flickr :turbojoe

“We’re crazy, but we’re writing a book in five days.”

- Anne Gentle

https://www.youtube.com/watch?v=lYfHEy6E2n0

Ask me. Challenge me. Find out.

flickr :candelabrumdanse

The hope “that deficiencies in program specifications could be made up by the skill of a technical writing

department… was misguided; the design of a program and the design of its specification must be

undertaken in parallel by the same person, and they must interact with each other.”

- C.A.R. Hoare, 1980

flickr :roswellsgirl