Docs as Code: the answer to development teams' perennial documentation woes?

Docs as Code provides a formal structure for how documentation should be created and formatted, making things easier for developers over time

Alongside writing and implementing software, creating good documentation should be factored into any project. However, many developers find it hard to keep these resources up to date over time.

Docs as Code is a methodology that helps streamline the writing, editing and publishing of documentation. Docs as Code treats all documentation as a codebase in its own right, using version control like Git to manage the actual documents. By writing in a plaintext language like Markdown and then pushing that documentation through an automated pipeline that tests the quality of the writing, developers can use the same approach to documentation as they do when building and publishing applications.

How to implement Docs as Code

Setting this up requires some effort, but it pays off in better documentation that is easier to manage over time. To get started with Docs as Code, first select a static site generator that will translate your plain text markup into HTML and JavaScript. Static site generators don't require the backend infrastructure that traditional sites need, which reduces infrastructure overhead and speeds up page loading times. While static site generators are available in multiple languages, the only requirement is that the team is familiar with the language to build the site and is happy with the user experience.

Once the static site generator is in place, the next step is to determine how to serve up the content. This will involve creating a Git repository for your content. GitHub and GitLab are both popular choices, and services like Netlify, Read the Docs and Cloudflare can all connect directly to both options.

Once your infrastructure is in place, it is time to test the documentation for overall quality. GitHub Actions and GitLab CI both offer ways to implement unit tests on pull requests made to the repository. This should include checking on adherence to a style guide, making sure there are no dead or broken links, and ensuring every document has appropriate title, social media descriptions and slugs.

Testing should be something that you start as early as possible by creating unit tests, but it should also be refined over time as you get more experience.

Once testing is in place, you can complete your publishing pipeline. That done, your Docs as Code website will be built based on pull requests, the process by which contributors signify that they'd like to add, remove or change something in a Git repository. When a pull request is merged into a designated branch, the site content will be created or updated based on the same process as code deployment.

Alongside this, there are a number of ways to preview your new and updated documentation pull requests. This is a great way to share documentation-in-progress with development teams and other writers without the need for them to build the site locally.

What to think about before the switch

Docs as Code is meant to streamline the writing, editing and publishing process, but it's not without trade-offs. For example, anyone responsible for documentation will need to have more software installed in order to contribute, and that software itself needs to be consistently versioned and maintained across the team. Doing this right means that any errors are easily reproduced and corrected when they arise.

Another consideration is how non-technical users can add value. While engineers and developers will find it easier to contribute and collaborate using the tools they use every day, non-technical users will have to learn how to get involved. Depending on the required involvement of other teams, Docs as Code may need more support to bring those teams up to par.

Collaboration on documents does need some coordination to work effectively, too. Without this, multiple contributors can work on the same content at the same time - as work typically takes place on a local machine - leading to collisions and confusion. This is not just a problem for Docs as Code approaches, but it should be acknowledged at the start. To solve this, clear signposting of who is responsible for a given task will help.

The last major consideration is that unit tests, integrations and publishing pipelines, while normally pretty durable, still need maintenance every once in a while. So, while a team using one of the solutions mentioned here is freed from having to manage and maintain databases and servers, they cannot divorce themselves from DevOps support without a working knowledge of all the parts in play.

The benefits of Docs as Code

At Linode, we made the switch to Docs as Code as part of our documentation team changes. There have been some great benefits from this move.

The first is document quality. Nothing in our Git repository is published without a stamp of approval from an editor, and every document must pass a number of tests before it can be published. We have a staging environment with Netlify to preview the individual pull requests, and another in place for previewing a release before we publish it in GitHub. In other words, it's easier for us to review documents and spot errors.

The second is that we have improved collaboration across teams. Everyone involved can see the actual document, styled just as it would be if we were to publish it, at every step of the way. If a document needs editing, contributors can make comments directly on that line in GitHub as a pull request. A side benefit of this is that it enforces review before the document is published, which keeps quality high.

Third, Docs as Code means writers can concentrate on writing rather than on presentation. Markdown has a very simple set of conventions and these can be quickly translated into HTML.

Lastly, the tools involved as part of Docs as Code deployments are compatible with the way web sites are created. This makes it easier for writers to make contributions to open source software and become more proactively engaged with the community.

Docs as Code is not something to introduce overnight. It requires planning and coordination. However, once in place, it helps developers create higher quality documentation and removes some of the hurdles around describing the code.

Docs as Code provides a formal structure for how documentation should be created and formatted, making things easier for developers over time. This leads to more frequent updates, better contributions and more accurate documentation, which makes life easier for both current team members and those reviewing the code in the future.

Andy Stevens is technical content manager at Linode