Git and GitHub for Documentation

1. COLLABORATING ON GIT AND GITHUB Anne Gentle FOR DOCUMENTATION

2. Questions at the end, but you can always ask me anything: documenting 20 cloud services across 130 GitHub repositories with 728 contributors in 4 years @annegentle, #CIDMOnline anne.gentle@rackspace.com 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 ﬁles rather than a “lock and checkout” model • Non-linear branching model

4. GITHUB VOCABULARY Repository Collection of stored code Organization Collection of repositories Fork Copy repository, copy of repository Issue Defects, tasks, or feature requests Pull Request Comparison of edits to see if team wants to accept changes Commit Point in time snapshot of repository with changes Branch Indicator of divergence from base

5. • Command line tool • Only place for all the commands GIT

6. • Web interface for git   repositories • http://github.com • Comments, reviews, emojis GITHUB

7. LET’S TALK ABOUT  PAIN POINTS “Meet the deadline.” “What can we get rid of before the deadline? I know…” “Let’s do Agile, but…” “Devs rule - docs drool.” ﬂickr:cobalt123

8. WRITING IN ISOLATION ﬂickr:mtischendorf

9. COLLABORATE WHERE USERS ARE • Curate the audience • Write with and for the audience • Reward the audience

10. I NEED A WRITER 1. Sacrifice your first-born for headcount and job description. 2. Come up with a pay scale. 3. Get a handful of resumes that don’t meet the requirements. 4. Cry. flickr:eclecticechoes

11. Ensure that contributors are valued and rewarded! • Sense of belonging • Pay it forward (reciprocity) • Effective, time-saving, user support • Reputation, recruiting MOTIVATIONS ﬂickr:seeminglee

12. LET’S CURATE Authors Processes Tools Mindsets Attitudes Jobs ﬂickr:roswellsgirl

13. TREAT DOCS LIKE CODE ﬂickr:roswellsgirl

14. LONGTAIL CONTRIBUTIONS • Rise of the niche • Finding like-minded people interested in your content • Dark corners of knowledge gap are ﬁlled with docs

15. THE DOCS SUCK In what way? Which page? How can I get it not to suck? ﬂickr:heidiandmatt

16. DOC ISSUES TRACKING • Tasks, outright errors, and feature requests • I’ll triage the issue and guide you in ﬁxing it, issue reporter • https://guides.github.com/ features/issues/

17. WRITERS NEVER GET REVIEWS Documentation system so separate from code system that technical reviews are through email or *gasp* frozen-in-time PDF ﬁles ﬂickr:elkaypics

18. REVIEWERS FIX DOCS “This is wrong, here’s how to ﬁx 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

19. UNFAIR TREATMENT Docs ghetto ﬂickr:mtischendorf

20. VALUE PROPOSITION Writer contributions, when treated like code, are valued equally with developer code

21. WHITE COAT TOOLS Closely guarded secrets of proprietary toolchains with expensive per-seat licenses. or Secret developer workﬂows are mysterious to writers. ﬂickr:darthnick

22. BEAUTIFUL DOCS • Widely accepted tooling built in the open so we make it work for us and for devs (readthedocs.org) • Simple markup • Flat ﬁle builds • We can patch and log issues against the tooling

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

24. CI/CD FOR ALL • Docs can be published automatically after reviewers merge them • 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 ﬂickr:pedrovezini

25. DRAFTS FOR REVIEWS • Static site generation from a branch or fork • Enables publishing both drafts and ﬁnal output ﬂickr:denverjeffrey

26. WHAT PAIRS WELL WITH GITHUB? • Simple markup: Markdown, Middleman, RST • GitHub Pages: http://pages.github.com • Static site generators: https://staticsitegenerators.net/ • Well-documented style guide and contributor guide • Open licensing: Creative Commons • PenFlip is “GitHub for Writers” • Borrowing development techniques

27. WHO USES GIT AND GITHUB FOR WRITING? • O’Reilly Media for book publishing • GitHub uses GitHub to document GitHub • OpenStack uses open source Git • Rackspace Cloud documentation uses GitHub

28. WHAT ARE SOME DIFFICULTIES? • Scope and scale questions • Ofﬁcial-ness • Identity • Naming ﬂickr:lamont_cranston

29. GITHUB BENEFITS • Collaborate where users are • Motivate more contributors; track and reward contributions • Version control; release management; CI/CD • Track issues for distributed assignments and improved quality • Create a quality bar for entry • Enable ﬁne-grained reviews and attract more reviewers • Automate tedious tasks • Coach writing skills and build better writers out of subject matter experts • Review incoming contributions; establish specialty teams for reviews • Build reputation and street credibility with metrics

30. ﬂickr:lnx DISTRIBUTED ASSIGNMENTS

31. You shall not pass… • test style guide • test syntax • test build QUALITY GATE ﬂickr:davebloggs007

32. END THE TEDIUM ENABLE THE ROBOTS • Build the docs and publish them to drafts or staging area • Docs are always available for reviews ﬂickr:hddod

33. COACH BETTER   WRITING • Become the experts and consultants 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 ﬂickr: philgaldys

34. CREATE TEAMS • We now divide the work by deliverable: user guides, install guides, conﬁguration guides • We scrape the code as often as we can to deliver continuously ﬂickr:mortimer

35. BUILD A REPUTATION • Measure quality and quantity • Count contributions and improvements • Compare over time; benchmark and reward ﬂickr:turbojoe

36. “We’re crazy, but we’re writing a book in ﬁve days.” - Anne Gentle https://www.youtube.com/ watch?v=lYfHEy6E2n0

37. Ask me. Challenge me. Find out. ﬂickr:candelabrumdanse

38. The hope “that deficiencies in program specifications could be made up by the skill of a technical writing department… was misguided; the design of a program and the design of its specification must be undertaken in parallel by the same person, and they must interact with each other.” - C.A.R. Hoare, 1980 flickr:roswellsgirl