Collaborating on GitHub for Open Source Documentation
5 likes3,005 views
The document discusses collaboration on GitHub for open-source documentation, highlighting the importance of treating documentation contributions like code. It explores motivations for contributors, tools, processes, and the challenges faced in documentation efforts. The presentation also emphasizes the need for integrating documentation with development workflows to improve quality and accessibility.
Collaborating on GitHub for Open Source Documentation
- 1. 2015 Collaborating on GitHub FOR OPEN SOURCE DOCUMENTATION Anne Gentle, Principal Engineer January 13, 2016 #writethedocs #atx
- 2. 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
- 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 3
- 4. 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
- 6. Collaborate Where Users Are ▪ Curate the audience ▪ Write with and for the audience ▪ Reward the audience 6
- 7. 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
- 8. 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
- 9. 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
- 10. 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
- 11. The Docs Suck ▪ In what way? ▪ Which page? ▪ How can I get it not to suck? 11
- 12. 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
- 13. 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
- 14. 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
- 16. Value Proposition Writer contributions, when treated like code, are valued equally with developer code 16
- 17. 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
- 18. 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. 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. 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
- 21. 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
- 22. ======================================== 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
- 23. 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
- 24. Flickr:lamont_cranston What Are Some Difficulties? ▪ Scope of reviews ▪ Scale questions ▪ Official-‐ness ▪ Naming 24
- 25. 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
- 26. 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
- 27. 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
- 28. 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
- 29. 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
- 30. “We’re crazy, but we’re writing a book in five days.” Anne Gentle https://youtube.com/watch?v-‐ IYfHEy6E2n0 30
- 31. Flickr:pedrovenzini What Are Some Difficulties? ▪ Scope and scale questions ▪ Official-‐ness ▪ Identity ▪ Naming 31 Flickr:candelabrumdanse Ask me. Challenge me. Find out.
- 32. MOTIVATIONS 32 Ensure that contributors are valued and rewarded! ▪ Sense of belonging ▪ Pay it forward (reciprocity) ▪ Effective, time-‐saving, user support ▪ Reputation, recruiting