What Is Docs As Code?
Docs As Code (also known as “Docs Like Code”) is a popular approach to delivering documentation for software projects.
There are three common themes that you can expect to see.
- Adopt an “agile” approach to content creation
- The whole team is responsible for content, not just the technical writers
- A culture of adaptation and improvement to both content, and processes, over time.
Docs As Code image copyright Anne Gentle. Released under an MIT license.
Why Do Docs As Code?
- Deliver valuable documentation faster with higher quality, because there are multiple voices working collaboratively
- Avoid documentation being a bottleneck in the release cycle
- Release technical writers to deliver higher value content (information architecture, customer experience, ....)
- Remove need for proprietary technical writing and publication tools.
How to do Docs As Code?
Use developer tools, and process, to create and deliver content. Specifically:
Text based file content with embedded, lightweight, markup tags. Examples include Markdown, reStructuredText, AsciiDoc
Developer based workflows. For example:
- Version Control using tools, such as Git
- Change control driven though bugs and feature requests tickets
- Content reviews and merges
Machine generated content
Automated testing and verification
Continuous delivery, using static site generators (for example Sphinx or Hugo). Note: This process is optional
Look at Docs As Code
Links we love
Check out these great links which can help you dive a little deeper into running the Docs As Code practice with your team, customers or stakeholders.