Collaborating on GitHub for Open Source Documentation
-
Upload
anne-gentle -
Category
Technology
-
view
2.728 -
download
2
Transcript of Collaborating on GitHub for Open Source Documentation
2015
Collaborating on GitHubFOR OPEN SOURCE DOCUMENTATION
Anne Gentle, Principal Engineer January 13, 2016
#writethedocs #atx
Questions at the end…
…but you can always ask me anything:
2
documenting 20 cloud services
across 130 GitHub repositories
With 800 docs contributors in 4 years
@annegentle, #writethedocs [email protected] www.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
3
GitHub Vocabulary
4
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
Github
5
WRITING IN ISOLATION
Flickr:mtischendorf
Collaborate Where Users Are
▪ Curate the audience
▪ Write with and for the audience
▪ Reward the audience
6
7
Motivations Ensure that contributors are valued and rewarded!
▪ Sense of belonging ▪ Pay it forward (reciprocity) ▪ Effective, time-‐saving, user support ▪ Reputation, recruiting
Flickr:elkaypics
MOTIVATIONS
8
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
MOTIVATIONS
9
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
Long Tail Contributions
▪ Rise of the niche ▪ Finding like-‐minded people interested in your content
▪ Dark corners of knowledge gap are filled with docs
10
The Docs Suck
▪ In what way? ▪ Which page? ▪ How can I get it not to suck?
11
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/features/issues/
12
Writers Never Get Reviews
Documentation system so separate from code system that technical reviews are through email
Or
*gasp*
Frozen-‐in-‐time PDF files
13
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
14
UNFAIRTREATMENT Docs ghetto
15
Flickr:mtischendorf
Value Proposition
Writer contributions, when treated like code, are valued equally with developer code
16
White Coat Tools
Closely guarded secrets of proprietary tool chains with expensive per-‐seat licenses
Or
Secret developer workflows are mysterious to writers
17
Flickr:darthnick
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
18
19
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
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/
continuous-integration-and-continuous-delivery-documentation
Flickr:pedrovenzini
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
21
======================================== 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
22
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
23
Flickr:lamont_cranston
What Are Some Difficulties?▪ Scope of reviews
▪ Scale questions
▪ Official-‐ness
▪ Naming
24
Flickr:pedrovenzini
What Are Some Difficulties?▪ Scope and scale questions
▪ Official-‐ness
▪ Identity
▪ Naming
25
Flickr:davebloggs007
QUALITY GATE You shall not pass… ▪ Test for unwanted
white space ▪ Test docs syntax ▪ Test docs build
Flickr:pedrovenzini
What Are Some Difficulties?▪ Scope and scale questions
▪ Official-‐ness
▪ Identity
▪ Naming
26
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
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
27
Flickr:philgaldys
Flickr:pedrovenzini
What Are Some Difficulties?▪ Scope and scale questions
▪ Official-‐ness
▪ Identity
▪ Naming
28
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
Flickr:pedrovenzini
What Are Some Difficulties?▪ Scope and scale questions
▪ Official-‐ness
▪ Identity
▪ Naming
29
Flickr:turbojoe
BUILD A REPUTATION ▪ Measure quality and quantity ▪ Count contributions and improvements
▪ Compare over time; benchmark and reward
“We’re crazy, but we’re writing a book in
five days.”
Anne Gentle
https://youtube.com/watch?v-‐IYfHEy6E2n0
30
Flickr:pedrovenzini
What Are Some Difficulties?▪ Scope and scale questions
▪ Official-‐ness
▪ Identity
▪ Naming
31
Flickr:candelabrumdanse
Ask me. Challenge me. Find out.
MOTIVATIONS
32
Ensure that contributors are valued and rewarded!
▪ Sense of belonging ▪ Pay it forward (reciprocity) ▪ Effective, time-‐saving, user support ▪ Reputation, recruiting