Learn how OpenStack and Rackspace use GitHub and development processes to create beautiful documentation. Presented at Grace Hopper October 2015.

1. 2015
Collaborating on
GitHub
FOR OPEN SOURCE
DOCUMENTATION
Anne Gentle
October 15, 2015
#GHC15
2015

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

3. 2015
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. 2015
GitHub Vocabulary
BRANCH
Indicator of
divergence
from base
COMMIT
Point in time
snapshot of
repository with
changes
FORK
Copy
repository,
copy of
repository
PUSH
Move changes
branch to
branch
ORGANIZATION
Collection of
repositories
PULL REQUEST
Comparison of
edits to see if
team wants to
accept changes
RESPOSITORY
Collection of
stored code or
documentation
ISSUE
Defects, tasks,
or feature
requests

5. 2015
Github
WRITING IN
ISOLATION
Flickr:mtischendorf

6. 2015
Collaborate Where Users Are
 Curate the
audience
 Write with and for
the audience
 Reward the
audience

7. 2015
MOTIVATIONS
Ensure that contributors are
valued and rewarded!
 Sense of belonging
 Pay it forward (reciprocity)
 Effective, time-saving, user support
 Reputation, recruiting
Flickr:elkaypics

8. 2015
MOTIVATIONS
Ensure that contributors are
valued and rewarded!
 Sense of belonging
 Pay it forward (reciprocity)
 Effective, time-saving, user support
 Reputation, recruiting
LET’S CURATE
Authors
Processes
Tools
Mindsets
Attitudes
Jobs
Flickr:roswellsgirl

9. 2015
MOTIVATIONS
Ensure that contributors are
valued and rewarded!
 Sense of belonging
 Pay it forward (reciprocity)
 Effective, time-saving, user support
 Reputation, recruiting
TREAT DOCS
LIKE CODE
Flickr:roswellsgirl

10. 2015
Long Tail Contributions
 Rise of the niche
 Finding like-minded
people interested in
your content
 Dark corners of
knowledge gap are
filled with docs

11. 2015
The Docs Suck
 In what way?
 Which page?
 How can I get it not
to suck?

12. 2015
Doc Issues Tracking
 Tasks, outright errors
and feature requests
 I’ll triage the issue and
guide you in fixing it,
issue reporter
 http://guides.github.com/f
eatures/issues/

13. 2015
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

14. 2015
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

15. 2015
UNFAIR
TREATMENT
Docs ghetto
Flickr:mtischendorf

16. 2015
Value Proposition
Writer contributions,
when treated like
code, are valued
equally with developer
code

17. 2015
White Coat Tools
Closely guarded secrets
of proprietary tool chains
with expensive per-seat
licenses
Or
Secret developer
workflows are
mysterious to writers
Flickr:darthnick

18. 2015
Beautiful Docs
 Widely accepted
tooling built in the
open so we can make it
work for us and for
devs (readthedocs.org)
 Simple markup
 Flat file builds
 We can patch and log
issues against the
tooling

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

20. 2015
CI/CD FOR ALL
 Docs can be published automatically after
reviewers merge the change
 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/cont
inuous-integration-and-continuous-
delivery-documentation
Flickr:pedrovenzini

21. 2015
What Pairs Well with GitHub?
 Simple markup: Markdown, RST
 GitHub Pages: http://pages.github.com
 Static site generators:
https://staticsitegenerators.net/
 Well-documented style guide and
contributor guide
 Open licensing: Creative Commons
 Borrowing development techniques

22. 2015
========================================
Discover the version number for a client
========================================
Run the following command to discover the version number for a
client:
.. code-block:: console
$ PROJECT --version
For example, to see the version number for the ``nova`` client, run the
following command:
.. code-block:: console
$ nova --version
2.31.0
Source | Output

23. 2015
Who Uses Git and GitHub?
 O’Reilly Media for book publishing
 GitHub uses GitHub to document GitHub
 OpenStack uses open source Git
 Rackspace Cloud documentation uses GitHub
 Many, many more organizations

24. 2015
Flickr:lamont_cranston
What Are Some
Difficulties?
 Scope of reviews
 Scale questions
 Official-ness
 Naming

25. 2015
Flickr:pedrovenzini
What Are Some
Difficulties?
 Scope and scale questions
 Official-ness
 Identity
 Naming
Flickr:davebloggs007
QUALITY GATE
You shall not pass…
 Test for unwanted
white space
 Test docs syntax
 Test docs build

26. 2015
Flickr:pedrovenzini
What Are Some
Difficulties?
 Scope and scale questions
 Official-ness
 Identity
 Naming
Flickr:hddod
END THE TEDIUM
ENABLE THE ROBOTS
 Build the docs and publish them
to drafts or staging area
 Docs are always available for
reviews

27. 2015
Flickr:pedrovenzini
Coach Better Writing
 Become the experts and
consultations 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

28. 2015
Flickr:pedrovenzini
What Are Some
Difficulties?
 Scope and scale questions
 Official-ness
 Identity
 Naming
Flickr:mortimer
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

29. 2015
Flickr:pedrovenzini
What Are Some
Difficulties?
 Scope and scale questions
 Official-ness
 Identity
 Naming
Flickr:turbojoe
BUILD A REPUTATION
 Measure quality and quantity
 Count contributions and
improvements
 Compare over time; benchmark
and reward

30. 2015
“We’re crazy, but
we’re writing a book
in five days.”
- Anne Gentle
https://youtube.com/watch?v-
IYfHEy6E2n0

31. 2015
Flickr:pedrovenzini
What Are Some
Difficulties?
 Scope and scale questions
 Official-ness
 Identity
 Naming
Flickr:candelabrumdanse
Ask me. Challenge me. Find out.

32. 2015
MOTIVATIONS
Ensure that contributors are
valued and rewarded!
 Sense of belonging
 Pay it forward (reciprocity)
 Effective, time-saving, user support
 Reputation, recruiting

33. 2015
Got Feedback?
Rate and Review the session using the GHC
Mobile App
To download visit www.gracehopper.org