What is Docs-as-Code and How Did it Revolutionize Google’s Docs Culture?
If you’re involved in software documentation, you may have heard of a trend called docs-as-code. It’s an increasingly popular approach to documentation and engineering workflows that are being used by corporations and small open source projects alike. What is it and why is it so popular?
What is Docs-as-Code?
Docs-as-code is a philosophy that follows that documentation should be developed the same way as code. It also emphasizes the value of documentation; it should be contributed to and maintained just as rigorously as code.
This means using the same tools and the same project management strategies to create documentation that is used in software development:
Version Control i.e. Git
Automation
Plain Text / Markdown
What are the Benefits?
Version Control
Git is free, open-source version control software not only for code but for text. You have a snapshot of your document throughout time and can go back to any moment to see who contributed what and when.
Automation
Linting is the automation of checking code for errors. When we write docs-as-code, linting automates checking for errors, grammar, and style. One of many possibilities of automation, these toolsets add strong support to documentation teams. An advanced example is the Python Sphynx tool.
Plain Text / Markdown
Writing in plain text allows you to use version control capabilities in Git to see exactly what changes from version to version. Markdown then offers fast and simple rendering.
Cultural Improvements and Integration
Writers and developers following the same workflow and using the same tools improve the culture around documentation as a product. Higher integration means documentation becomes co-owned and co-valued. Using the same tools allows all stakeholders to speak the same language and collaborate on documentation.
How Technical Writers Engineered Google’s Documentation Culture
In this 2015 Write the Docs talk, Google tech writer Riona MacNamara describes facing burnout in a struggling docs culture. With a lack of trust and accessibility in documentation, thousands of engineers, and a handful of technical writers it just wasn’t working.
She reports that after attending the years previous Write the Docs conference and learning about the docs-as-code philosophy, Riona and her co-workers made a monumental impact in Google’s documentation culture and workflow.
Figure 1. Google’s docs-as-code product is called “g3docs”.
By prioritizing their engineers as the users, they created a docs-as-code system called “g3docs” at Google that enabled engineers to find, create, and maintain docs by keeping documentation in a Markdown format next to its associated code and rendering it at a logical URL. This integrated workflow meant that documentation did not become another competing system that continued to fracture documentation from engineering. The docs-as-code philosophy solved the crucial problem they were facing. As she emphasized, “documentation will never be a part of engineering culture until it is integrated into the codebase and engineering workflow.”
Spotify, Twitter, and Microsoft are just a few of the other major players to develop a docs-as-code culture in their companies and find value in a culture of docs.
Learn More about Docs-as-Code
The docs-as-code trend shows no signs of slowing down as tech continues to grow and the value of documentation continues to prove itself. If you’re interested in learning more about docs as code or how to implement it as a writer, keep reading the links below.
References
Riona Macnamara. Documentation, Disrupted: How Two Technical Writers Changed Google Engineering Culture, NextDayVideo. YouTube, YouTube, 19 May 2015, www.youtube.com/watch?v=EnB8GtPuauw.