Collaborating on GitHub for Open Source Documentation

Editor's Notes

• #2: Welcome everyone, I can’t wait to tell you about my experiences collaborating on GitHub. If I told you we had over 1900 documentation changes you might rightly ask, in what time period and how many people are on your team. If I said 6 months time with over 300 people you might snort some diet Coke out of your nose. Yes, we have evidence that our techniques can give us over 300 doc changes in a month. Let’s talk more about how.
• #3: I’m Anne Gentle and you can ask me anything, but I’ll ask that you jot down your questions and save them until the end. I’ve been working on open source documentation since 2007 or so and working on OpenStack at Rackspace for almost five years. OpenStack offers open source cloud computing software. Developer contributors number in the 4,000s. I wrote the book, Conversation and Community: The Social Web for Documentation and I’ve been working on the principals in practice ever since. Today I’m going to tell some stories about documentation across multiple GitHub repositories. Let’s get started.
• #4: Like many tools, git and GitHub were created by fire — through a pressing need for performant and efficient source control management for the Linux kernel. I’ve found that the principles in the social web for coding works extremely well for documentation as well. Plus, our modern documentation needs are very driven by the way software today is developed - tightly with code, Agile methods, and web output first, print output secondary if at all. Releasing with software matters also.
• #5: Yes, fork can be a verb and a noun. These terms can mean you will have decisions to make about information architecture so pay attention. You can also keep docs in a source code repository then the developers will have to review all your changes prior to merging them in. Unlike traditional source code management, branches are not full copies of entire code base so they are “cheap” and “fast.”
• #6: Assignments over the wall Project-centric instead of user-centric Deadlines set by dev not docs
• #7: Devs write for dev, operators write for operators, users write for users
• #8: This is not about free labor. Contributors should be highly, highly valued and rewarded.
• #9: Let’s curate authors, not just content. Let’s curate processes to create jobs.
• #11: OpenStack Glossary appearing from a sys admin in Iowa on the wiki; bringing it into the official OpenStack docs. Logged a doc bug late in my work day, came in to a patch the next morning that fixed it. The Long Tail for open source docs is the obscure knowledge gathering and hard-to-find info
• #12: This is my frowny bug face. What can we do about it? Issue tracking.
• #13: Tell me which page. Tell me your expectations for that page. Tell me how to fix it.
• #15: We have systems in place that let us merge as many as 50 doc patches a day, though typically it's about 15. Each reviewer who can publish must adhere to our review rules. Truth: Working in the same collaboration tools as technical people gives better reviews. Story of install guide: I wrote the first one in 2012, hired a contractor for a revision, and then another person completely testing the entire install guide for OpenStack since he had to do a proof of concept at work, testing it completely.
• #16: In Open Source, we don’t want the docs group to be misunderstood or second-class citizens. Take your seat at the contributor table.
• #17: Writers contributions, when treated like code, are valued equally with developer coding. We give free passes to the OpenStack Summit for docs contributions because the patching and review processes are identical.
• #18: Imagining a doctor or surgeon with very specialized expensive tooling or Developers arrogantly think they rule despite a lack of documentation so no one can use their code
• #19: This leads to continuous integration for docs.
• #20: Continuous Integration/Continuous Deployment Mimic production environment in your local environment.
• #21: Development teams do continuous integration and deployment; completely mimicking their local environment in production and continuously updating the code and product to make it better Example: scrape the current code for reference information and use the code itself to build the docs. - documented over 6,000 configuration options this way working on REST API docs this way as well, building Swagger
• #22: 399 static site generators. So let’s see what this looks like in practice.
• #23: The source file in this case is in RST, ReStructuredText, used by Python developers and for making web pages. You can also view it on GitHub to see it rendered with their simple renderer. Lastly, see the built documentation on the docs.openstack.org site with more navigation and web design and styling.
• #24: Technical authors want to use technical tools.
• #25: Writers tend to, well, review writing quality first, technical quality second. Can still have an “us vs. them” mentality from reviewers when doc writers nit pick about style rather than adding value. Who’s the audience? Multiple hats for multiple audiences What’s the name? Naming is the toughest problem in docs Scaling across repositories is really difficult. People still write content in their blog and ask you to bring it in to official doc. Scope for “official” can be difficult.
• #26: Round the clock publishing, reviewers burden lifted by having gate checks.
• #27: Lets experts review for content and organization; do higher level technical editing and technical tests as well on the content. Curate the content as a focus rather than messing around a bunch with the process. We have even automated the translation tool exports and imports. Also when sharing content we can automate the file copying.
• #28: I’ve never had a developer not help me improve my programming skills. Let’s reciprocate. Just today I made a simple suggestion for someone to eliminate the use of “will” and he was super excited to delete those and improve his writing.
• #29: Specialty teams now abound — subject matter experts for security, for high availability. This lets us deliver more complex content more often.
• #30: GitHub shows who is contributing and to what areas. I’m now an O’Reilly author along with six other collaborators. The people with the knowledge can become better writers and learn more empathy by writing for the users. This, to me, is the New Bliss, the new way to work on documentation together. What does it look like in practice? Let’s take a look.
• #31: https://www.youtube.com/watch?v=lYfHEy6E2n0 A couple of notes: that sprint tool is moving to GitHub. Also this book was then edited by O’Reilly and offered a set of info not available another way. Each author had run OpenStack for at least six months in production and brought all their notes and docs as well, wanting to share with others. “We’ll help them hate their managers just a little bit less.” - Tom Fifield “Our facilitator is whipping us repeatedly to get us to work on the content repeatedly so we’re writing the book in about four days.” - Everett Toews
• #32: Have I set a vision that seems attainable? What are your questions? After this I have a final vision for you that should show you what’s old is new again.
• #33: Booth 1001 Tight collaboration, equal footing with dev, and a value proposition that puts both dev and doc on the path to well-loved customer experience. The new bliss: What docs like code looks like What happens when you release with code What happens when you invite developers and users to write with you This new normal for documentation, imagine what it can do for you
• #34: This is the last slide and must be included in the slide deck