Docs as Code – An Approach to Improve the API Documentation Process

‘Docs as code’ refers to the practice of writing documentation using the same tools and processes that developers use to write code. This means that documentation is :

• Authored using text files such as Markdown or LaTeX
• Version controlled using Git
• Updated by creating pull requests
• Published using CI/CD workflows

Keeping Everything in Sync with API Updates

How can this approach lead to better documentation? Here’s a scenario:

Imagine a developer catches a typo in your API documentation. They do not have access to your documentation tool so the technical writer responsible for maintaining the docs is notified. They fix the typo and are ready to publish the updated documentation. However, your documentation tool, like most documentation tools, doesn’t support branching. So publishing this change will cause all ‘pending review’ changes to go live as well. Therefore, you are forced to put up with stale documentation until all pending changes are reviewed and approved.

If only your documentation tool supported branching…

5 Reasons Why You Should Use Docs as Code

If you are creating documentation using an off-the-shelf documentation tool, chances are, you’ve encountered a problem that would be trivial to solve using developer tools. Therefore, you can elevate your documentation writing experience by adopting those same tools. 

Below are some of the benefits you can gain by using a docs as code approach.

1- Smaller Feedback Loops

Getting feedback from stakeholders is essential to creating great documentation. This is harder than it sounds with traditional documentation tools. Sometimes, you may have to wait for feedback until after the changes go live. 

With docs as code, if a developer makes a minor change, they can preview their API portal or documentation by deploying their feature branches and gather feedback from relevant stakeholders. This paves the way for a smaller feedback loop and faster API documentation updates.

2- Instant Updates after API Changes

An organization may have a team of engineers, technical writers, and managers to maintain its API, where each team member has their own contribution. 

However, the responsibility of updating and publishing the documentation is delegated to a select few individuals. This centralized ownership means that other team members are unable to independently update the documentation. Even a minor release depends on the documentation owner’s availability. This not only increases the lead time for documentation updates but discourages frequent improvements or forces teams to batch together numerous changes over weeks or months of development.

However, if the API documentation is automated, that small change can be made independently without waiting for other team members. For instance, technical writers can deploy content updates and engineers can update the appearance or configuration of API specifications independent of each other. Furthermore, team members not tasked with maintaining API documentation can also suggest edits and send PRs for minor improvements.

3- Supporting Version Control 

Version control enables the storage of a complete historical record of the development process and of all the previous changes made by every developer for your API documentation. Having this record, you have the ability to confidently branch out with experimental API versions, knowing that if the experiment fails, you roll back up to an earlier version. 

Furthermore with an audit log at your fingertips, fixing bugs is super quick, since you can track the exact commit that caused your documentation to break and easily roll back to the last working commit if needed. This is the reason why CI/CD for your API documentation is a no-brainer.

4- Efficient Collaboration

By providing automation and hosting source code on a service like GitHub, every team developer has access to the API documentation. There, are no restrictions on the number of people who can contribute, as is customary with most SaaS-based documentation solutions. 

Moreover, there is no need to learn a new tool because contributing to the documentation is as easy as committing to a Git repository. With the entire team working collaboratively, you can rest assured that your documentation will always be up to date and free of inconsistencies.

5- Leveraging Familiar Tools & Workflows

Platforms like GitHub, GitLab, or Bitbucket have huge app ecosystems that make the lives of developers much easier by automating the build, integration, and deployment of code. It is difficult for any off-the-shelf documentation tool to match the sophistication of tooling available for these platforms; tooling that most developers are already familiar with.

This eliminates the need for contributors to learn new tooling just to be able to contribute to documentation. They can use their favorite text editor, source control system, and deployment tool to contribute to API documentation. This eliminates any friction that might be caused by being restricted to the tools provided by an API documentation solution.

Seamless Autogeneration of API Documentation with APIMatic

To enjoy and completely utilize an automated experience, APIMatic provides autogeneration of API documentation on each API update. APIMatic’s comprehensive API documentation contains language-specific API reference, multiple language-native SDK documentation, custom Markdown guides, autogenerated getting started manuals, and much more. You only need to provide your API specification in any supported format and APIMatic handles the rest. 

Similarly, APIMatic provides docs as code offering comprehensive API documentation, customizable guides, and an API Portal configuration managed as code. You can store this code in your Git repository and collaborate with the whole team while creating as many branches for individual features as you want and setting up branch deploys. You can also set up automation using tools like GitHub Actions. To see this process in action, take a look at this blog on Docs as Code Made Easy using APIMatic and GitHub Actions. Try APIMatic now and enjoy our automatically generated API documentation!