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 anne.gentle@rackspace.com 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