Docs as Code¶
Docs as Code refers to a philosophy that you should be writing documentation with the same tools you use to write code. This means following the same workflows and integrating into development teams. It enables a culture where writers and developers both feel ownership of documentation, and work together to make it as good as possible.
Generally a docs as Code approach gives you the following benefits:
- Writers integrate better with development teams
- Developers will often write a first draft of documentation
- You can block merging of new features if they don’t include documentation, which incentivizes developers to write about features while they are fresh
There is a lot more to building a proper Docs as Code workflow. There are a couple books we recommend that you check out:
- Docs Like Code - Anne Gentle
- Modern Technical Writing - Andrew Etter
Docs as Code at Write the Docs¶
Write the Docs has had a number of talks that touch on this topic over the years.
2015 North America
- Riona MacNamara talked about how adopting Docs as Code has completely transformed how Google does documentation.
2016 North America
- We had a panel with folks from Rackspace, Microsoft, Balsamiq, and Twitter, all talking about how they are adopting these practices.
- Margaret Eker and Jennifer Roundeau from Rackspace & Capital One, it was a great overview of Docs as Code.
- Rachel Whitten from Pantheon give a talk on their implementation of these approaches.
The Docs as Code concepts are widely practiced in the software industry, and are gaining adoption in the writing community.