Documentation As Code

What is Docs-as-Code?

Docs-as-Code is an engineering-centered way of approaching technical documentation. Rather than placing the documentation within a traditional platform, such as a CRM, it keeps it inside the code repository and uses tools to publish the content to a greater audience.

Why would you need Docs-as-Code?

There is a broad audience for technical documentation. Ensuring that this documentation is both relevant and up-to-date is critical. Time and effort are wasted when writing the documentation take just as long as the coding process.

Benefits of Docs-as-Code

Coders live most comfortably within the code and often less within the documentation world. Every coder I know recognizes the value of documentation but is loathe to be the one producing it. Most documentation methods require the coder to switch focus in and out of the code, like switching between English and Spanish. Leveraging tools and techniques that integrate documentation with code creation mitigate this painful focus switch.

Most codebases include a README and often even a CHANGELOG text file which are updated and checked in with the code itself. Likewise, coders are often familiar and comfortable with creating inline comments as they define variables or even explain certain decisions. The Docs-as-Code approach expands on these standard practices. In addition, static site generators are leveraged to translate these simple text documents into more user-friendly websites and document repositories.

Documentation Lives with the Code:

Since the documentation is created and maintained within the same repository as the code it describes, there is no longer any need to hunt for it. Further, keeping it within the git or other software repo benefits from the same version control as the code.

Low-cost maintenance:

By including the publishing step within the build pipeline, the documentation is always up to date. There is no need for anyone to update a separate document, website, or blog. The documentation is built and released for public consumption alongside the code.

What’s Required For Docs-as-Code

Nothing is needed outside a standard code repo and a static site generator. Most important is the adoption of documentation as part of the development process.

The docs:

The documentation itself is written the same as other include type files. These are simple text files written in standard markup or even plain text. The developers and the static site generator determine the specifics of this. The most important thing is that it is consistent and fits seamlessly with the rest of the coding process.

The publisher:

To transform the electronic chicken scratch of the developers into beautifully published written documents, you will need a static site generator. There are several of these to choose from, mainly depending on the code language. While it is possible to mix and match, it makes more sense to keep to the same language whenever possible.

A few examples are:

• Docusaurus written in Node.js

• Hugo written in Go

• Jekyll written in Ruby

Documentation Matters

Documentation is vital for users trying to learn how to use the product to engineers trying to understand the code base. It should be smooth for everyone involved, and implementing a Docs-as-Code approach can make this happen.

Limitations

Adopting a Docs-as-Code methodology is not a universal fix for documentation issues. Look for a follow-up article where I explore the limitations and offer possible alternatives.