On the Write The Docs London meetup in January speakers from leading Git code repositories talked about how their teams dogfood their own tools to do their documentation. Version the Docs covered Bitbucket and GitLab, but we missed a GitHub presentation. To fill this gap, we interviewed Anne Gentle about GitHub, treating docs like code, and community contributions to documentation.
Hi Anne, could you please introduce yourself in a few sentences?
Anne Gentle: Hi, I’m Anne Gentle and I live in Austin Texas with my family. I work as a product manager at Cisco, on a private cloud offering based on OpenStack, a collection of open source projects that run cloud services. My goals are to provide customer success journeys as they move workloads to the cloud, through docs and support sites, keeping doc automation in mind and in step with developer workflows.
Your book, Docs Like Code, is based on the idea of using Git to manage documentation. Good documentation is a crucial part of a project’s success. However, the idea of writing documentation following the developer workflow is not trivial. What are the main advantages to treating documentation as you treat code?
Anne Gentle: The main advantages are efficiency, fit with collaborators, and market or business needs. When you add doc automation and reviews to your workflow, you get tighter collaboration, workflows and reviews that match step with development, automation of mundane tasks such as building output, giving you efficiency gains, and you can add in user experience improvements by using modern web tools for documentation sites.
I also believe that the business needs when providing docs for services mean you should automate your doc builds as those services are often automated. Plus, with the rise of REST API documentation needs, tight integration with developer workflows gives you a market advantage in empathy for the developer user and meeting the expectations of many of today’s doc consumers.
There are definitely particular environments where you can gain those advantages or even require them in order to work at your peak.
How does thinking about documentation change under a docs like code approach?
Anne Gentle: One of my first, best hopes in changing mindsets about documentation is to remove the artificial hierarchy that already exists in high tech -- that somehow there’s a developer, then tester, then writer hierarchy in technical knowledge. Or perhaps it’s an unwritten set of rules for “lording” over others, such as: “first network administrator, then system administrator, then database administrator, then email server administrator.” We all know these are fake structures in our heads, yet many cultures still look down on certain roles on a team.
With a docs like code approach, writers show a willingness to adopt developer tools and techniques to gain better collaboration points with developers, and developers see that working on docs can both increase quality of their code, provide beautiful documentation sites crafted carefully with excellent web development, and save them time in answering questions later.
How can the non-linear branching model improve the work of content creators and/or documentarians?
Anne Gentle: In some environments, content creators have become accustomed to “ownership” of certain deliverables. Meaning, they were the only ones responsible for the final content and form. So a branching model may not be the only adjustment to make, they may also need to get used to an optimistic merge version control system instead of a pessimistic “locking” version control system. When you cannot lock a file long enough to do complete edits, and someone else edits the file ahead of you, it can be a bit disconcerting when you merge the content later.
That said, I firmly believe that no one can know “everything” and having single owners of any given deliverable is a tough workplace to be in. Non-linear branches and independent but coordinated content efforts are the new normal. Overall, teams create better technical content when a single person is not isolated to a particular role, alone and guessing at the edges of technical use cases. The optimistic merge offers the ability to deep-dive on particular features. Still, my technical editor, who now works in GitHub only, misses the days when she could do an overall quality check of a final deliverable instead of having to review small pieces of a docs site. Teams gain higher quality content when they can do both deep and wide quality reviews.
Bitbucket and GitLab have been working on similar features to enable Git-based documentation workflows. What made you choose GitHub over the other tools?
Anne Gentle: Honestly, I hadn’t had an opportunity to use Bitbucket or GitLab until I came to Cisco in 2016. Our Cisco DevNet site at developer.cisco.com is all built using Bitbucket and Git repos. Since much of my knowledge and content was based in using Git and Gerrit for more than five years in OpenStack, and I wanted to learn more about GitHub through other projects, those are the main toolsets I discuss in the book.
That said, I’m working on a second edition now, and through feedback from readers of the first edition, I’m adding information about some nice features provided by GitLab through their built-in CI and a cool feature called Review Apps that lets product managers and testers and others review entire builds as early as possible. I also had a sense that the largest starting set of users for a docs-like-code approach may be through the GitHub ecosystem, and my goal was to onboard as many people as possible if they were first starting an evaluation. I’d love to hear from more people about additional Git-based workflows that work well for them.
GitHub also enables community contributions to docs. In your experience does this ever work?
Anne Gentle: I’m an early adopter and advocate for community documentation, and wrote Collaboration and Community: The Social Web for Documentation in 2009, with a second edition in 2011. I explored the various ways we all collaborate on documentation deliverables, and in my mind, treating docs like code is the next evolution of collaboration in producing modern documentation.
So, a hearty, “Yes” in answer to this question, though it’s not exactly the toolset that makes contribution models work, but content attitudes, culture, leadership, and governance that provide the scaffolding for community contributions. We have had a lot of success with collaborative docs-as-code in OpenStack, and you can see examples in many open source communities. It does take a strong vision and leadership, patience and guidance, to have any measurable level of success with community docs. I believe these contributions are highly valuable, even essential, when motivated by a sense of belonging and shared purpose.
Could you describe a recommended/ideal content workflow for GitHub?
Anne Gentle: Depending on the top priority outcome, I’ll certainly recommend integrating tightly with developer teams to get a good result from any chosen content workflow. Teaching reviewers not to merge code unless it has docs included is a great way to integrate docs into a development workflow, for example. The tighter the integration between docs and code, the easier it is to keep the two synchronized.
On the other hand, if you intend to have a separate doc specialty team, with their own repo, you could choose a workflow that matches your publishing intentions best. If you want continuous publishing, then publish from a master branch at all times, and automate as much as possible.
In the Docs Like Code book, we go through many workflows and the pros and cons of each workflow. If you want to prioritize collaboration and technical reviews above all else, pick the workflow everyone else is already using. If you want to prioritize work on proprietary features in an access-controlled workflow, you likely need to use feature branches in your workflow and control flow of content from branch-to-branch in your process.
When I attended the Write the Docs conference in Portland in 2017, I realized that we hadn’t addressed the increasing complexity involved in released documentation sites, especially when the complexity increases when you need to output a set of versioned docs. The Read the Docs site specifies exactly how their CI system uses source control to output versioned docs sites in http://docs.readthedocs.io/en/latest/versions.html. When you need to set your own workflows and access control on either the source or output, the complexity increases, and the Read the Docs model is a great starting point. I’m already working on a second edition with a new chapter about releasing documentation sites when using docs as code.
What do you recommend for a newcomer, what is the best way to start writing documentation using GitHub?
Anne Gentle: I’ll always answer this question with, look into contributing to an open source project! In the Docs Like Code book, I provide a brief tutorial for getting started, by pointing to the Bootstrap project, because the team tends to triage their GitHub Issues so that a person could “walk up” to the repo and find a small bug to work on. Look for projects that triage their bugs, use “docs” labels, or “low-hanging-fruit” indicating something that would help a newcomer get started.
If you’re interested in reading additional articles about people already working in this way, or a series of emailed lessons about treating docs like code, go to docslikecode.com.