collaborating on github for open source documentation

2015

Collaborating on GitHubFOR OPEN SOURCE DOCUMENTATION

Anne GentleOctober 15, 2015

#GHC15

2015

2015

Questions at the end……but you can always

ask me anything:

documenting 20 cloud servicesacross 130 GitHub repositories

With 800 docs contributors in 4 years

@annegentle, #[email protected]

mailto:[email protected]

http://www.justwriteclick.com/

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

2015

GitHub VocabularyBRANCH

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

2015

Github

WRITING IN ISOLATION

Flickr:mtischendorf

2015

Collaborate Where Users Are

Curate the audience

Write with and for the audience

Reward the audience

2015

MOTIVATIONSEnsure that contributors are valued and rewarded!

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

Flickr:elkaypics

2015



LET’S CURATEAuthors

ProcessesTools

MindsetsAttitudes

Jobs

Flickr:roswellsgirl

2015



TREAT DOCSLIKE CODE

Flickr:roswellsgirl

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

2015

The Docs Suck

In what way? Which page? How can I get it not

to suck?

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/features/issues/



2015

Writers Never Get ReviewsDocumentation system so separate from code system that technical reviews are through email

Or

*gasp*

Frozen-in-time PDF filesFlickr:elkaypics

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

2015

UNFAIRTREATMENT

Docs ghetto

Flickr:mtischendorf

2015

Value PropositionWriter contributions, when treated like code, are valued equally with developer code

2015

White Coat ToolsClosely guarded secrets of proprietary tool chains with expensive per-seat licenses

Or

Secret developer workflows are mysterious to writers

Flickr:darthnick

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

2015

ONLY DEVTEAMS GET CI/CD

Deploying containers and micro services oh my.

Docs, use some horrifyingly slow proprietary tool, kthnxbai.

Flickr:photohome_uk

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/

continuous-integration-and-continuous-delivery-documentation

Flickr:pedrovenzini

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

http://pages.github.com/

https://staticsitegenerators.net/

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 thefollowing command:

.. code-block:: console

$ nova --version 2.31.0

Source | Output

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

2015

Flickr:lamont_cranston

What Are SomeDifficulties?

Scope of reviews Scale questions Official-ness Naming

2015

Flickr:pedrovenzini


Scope and scale questions Official-ness Identity Naming

Flickr:davebloggs007

QUALITY GATEYou shall not pass… Test for unwanted

white space Test docs syntax Test docs build

2015

Flickr:pedrovenzini



Flickr:hddod

END THE TEDIUMENABLE THE ROBOTS Build the docs and publish them

to drafts or staging area Docs are always available for

reviews

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

2015

Flickr:pedrovenzini



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

2015

Flickr:pedrovenzini



Flickr:turbojoe

BUILD A REPUTATION Measure quality and quantity Count contributions and

improvements Compare over time; benchmark

and reward

2015

“We’re crazy, but we’re writing a book

in five days.”- Anne Gentle

https://youtube.com/watch?v-IYfHEy6E2n0

2015

Flickr:pedrovenzini



Flickr:candelabrumdanse

Ask me. Challenge me. Find out.

2015



2015

Got Feedback?

Rate and Review the session using the GHC Mobile App

To download visit www.gracehopper.org

http://www.gracehopper.org/

collaborating on github for open source documentation

Technology