1.
COLLABORATING ON GIT AND GITHUB
Anne Gentle
FOR DOCUMENTATION

2.
Questions at the end, but you
can always ask me anything:
documenting 20 cloud services
across 130 GitHub repositories
with 728 contributors in 4 years
@annegentle, #CIDMOnline
anne.gentle@rackspace.com
www.justwriteclick.com

3.
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

4.
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

5.
• Command line tool
• Only place for all the
commands
GIT

6.
• Web interface for git
repositories
• http://github.com
• Comments, reviews, emojis
GITHUB

7.
LET’S TALK ABOUT
PAIN 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

8.
WRITING IN
ISOLATION
flickr:mtischendorf

9.
COLLABORATE
WHERE
USERS ARE
• Curate the audience
• Write with and for the audience
• Reward the audience

10.
I NEED A WRITER
1. 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

11.
Ensure that contributors are
valued and rewarded!
• Sense of belonging
• Pay it forward (reciprocity)
• Effective, time-saving, user support
• Reputation, recruiting
MOTIVATIONS
flickr:seeminglee

12.
LET’S CURATE
Authors
Processes
Tools
Mindsets
Attitudes
Jobs
flickr:roswellsgirl

13.
TREAT DOCS
LIKE CODE
flickr:roswellsgirl

14.
LONGTAIL
CONTRIBUTIONS
• Rise of the niche
• Finding like-minded people
interested in your content
• Dark corners of knowledge gap
are filled with docs

15.
THE DOCS SUCK
In what way?
Which page?
How can I get it not to suck?
flickr:heidiandmatt

16.
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/

17.
WRITERS NEVER
GET REVIEWS
Documentation system so separate
from code system that technical
reviews are through email
or
*gasp*
frozen-in-time PDF files
flickr:elkaypics

18.
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

19.
UNFAIR
TREATMENT
Docs ghetto
flickr:mtischendorf

20.
VALUE
PROPOSITION
Writer contributions, when
treated like code, are valued
equally with developer code

21.
WHITE COAT
TOOLS
Closely guarded secrets of
proprietary toolchains with
expensive per-seat licenses.
or
Secret developer workflows
are mysterious to writers.
flickr:darthnick

22.
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

23.
ONLY DEV TEAMS
GET CI/CD
Deploying containers and micro
services oh my.
Docs, use some horrifyingly slow
proprietary tool, kthnxbai.
flickr: photohome_uk

24.
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

25.
DRAFTS FOR REVIEWS
• Static site generation
from a branch or fork
• Enables publishing both
drafts and final output
flickr:denverjeffrey

26.
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

27.
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

28.
WHAT ARE SOME
DIFFICULTIES?
• Scope and scale questions
• Official-ness
• Identity
• Naming
flickr:lamont_cranston

29.
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

30.
flickr:lnx
DISTRIBUTED
ASSIGNMENTS

31.
You shall not pass…
• test style guide
• test syntax
• test build
QUALITY GATE
flickr:davebloggs007

32.
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

33.
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

34.
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

35.
BUILD A
REPUTATION
• Measure quality and
quantity
• Count contributions
and improvements
• Compare over time;
benchmark and reward
flickr:turbojoe

36.
“We’re crazy, but we’re
writing a book in five days.”
- Anne Gentle
https://www.youtube.com/
watch?v=lYfHEy6E2n0

37.
Ask me. Challenge me. Find out.
flickr:candelabrumdanse

38.
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