Docs as Code
— REST API, Docs-as-code, OpenAPI — 2 min read
Docs-as-code is a way to publish technical documentation using the same tools that are used to write & publish code. This allows to greater automation of repetitive tasks and, in many cases, increased ease of collaboration between writers and subject matter experts. With the proper implementation it can also help enforce your style guide and catch common mistakes such as broken links.
This article is specific to documentation for REST APIs in an agile environment.
How to Implement
Basics
A basic docs-as-code workflow includes the following:
- An OpenAPI (Swagger) specification
- Version control
- Linters: for prose and code
- CI/CD
Why Docs As Code:
Some benefits of a docs-as-code toolchain include:
- Increased collaboration
- Writers submit changes via pull requests which can easily be reviewed by developers or other subject matter experts (SMEs).
- Developers can make changes (write whole drafts, update articles or the OpenAPI spec) which can be seen, edited and reviewed by writers.
- No need to be pinging people on Slack or email!
- Writers are integrated into the development team. It's often hard for writers to find their place on a technology team—using the same tools helps them feel integrated.
- Maintainability
- Unit tests and linters reduce the amount of manual testing required before release.
- Writers have more time to focus on writing and less on tedious work
- Version control:
- Allows for easy documentation rollbacks in case of software rollbacks or mistakes.
- Tags can link doc versions to software releases (some SaaS docs tools include feature this built-in).
- In an agile environment docs can be included in the definition of done-done and easily reviewed using the same tools as the code.
Overall, a well-implemented docs-as-code system can save you time, money and energy. It's my favorite way to do docs and can be a great benefit to your whole team.
Why Not?
As with any toolchain there are cons to using docs-as-code:
- Tech writers may prefer not to write using Markdown or a text editor.
- You have to maintain the 'code' part of docs-as-code: You either need a writer with dev skills or to dedicate a developer to fix any issues that may arise. This can present a particular problem if the toolchain chosen for docs differs from your software stack. (Ideally your doc tools should be the same as your software stack.)
Further Reading
Here are some helpful resources if you'd like to learn more: