Docs as Code

Docs as Code (DaC) is a philosophy and set of practices where you treat documentation the same way you treat your software code. This means:

• Plain Text Formats: Writing documentation is simple, human-readable file formats like Markdown, reStructuredText, or AsciiDoc.
• Version Control: Using a version control system like Git to track changes, collaborate with others, and easily roll back edits to the documentation.
• Automation: Employing tools for automated testing, linting (checking for style and consistency), and building/publishing processes for your documentation.
• CI/CD Pipelines: Potentially setting up continuous integration and delivery (CI/CD) pipelines that take care of automatically building, testing, and publishing documentation when code changes occur.

Benefits

• Better Collaboration: Developers and technical writers can easily work together on the same code repository, fostering teamwork and streamlined processes.
• Synchronization: Documentation seamlessly evolves alongside code changes, ensuring that your docs are always up-to-date and accurate.
• Quality Control: Version control allows you to see every change made to documentation, enhancing quality and allowing for easy recovery of previous versions.

Shu Juan Cheong, a technical content developer at Grab wrote about how Grab adopted Docs-as-Code:¹

One of the most widely-known examples is Spotify, that uses Docs-as-Code to publish documentation in an internal developer portal.

Since the start of 2021, Grab has also adopted a Docs-as-Code to publish documentation in an internal developer portal.

Technical documentation is placed in the same repository as the code, making it easier for engineers to write and update.

Like many other companies on the same journey, Grab is rather big and our engineers are split into many different teams. Within each team, technical documentation can be stored on different platforms and in different formats, e.g. Google Drive documents, text files, etc. This makes it hard to find relevant information, especially if you are trying to find another team’s documentation. … even if people could find the information, there was a good chance that it would not be up to date.

To address these issues, we need a centralised platform, a single source of truth, so that people can find and discover technical documentation easily.

Here’s a brief overview of the process:

1. Create a dedicated docs folder in a Git repository.
2. Push Markdown files into the docs folder.
3. Configure the developer portal to publish docs from the respective code repository.

The latest version of the documentation will automatically be built and published in the developer portal.

This way, technical documentation is closer to the source code and integrated into the code development process. Writing and updating technical documentation becomes part of writing code, and this encourages engineers to keep documentation updated.

Jen Lanbourne, a technical writer at Government Digital Service (GDS) in United Kingdom also wrote about why they use a “docs as code” approach for technical documentation:²

By working in the open, anyone can contribute to our documentation, and the whole team has shared ownership of the content. It’s a deliberate departure from a more traditional model where a technical writer might sit in another department writing documentation using a different project management approach to their technical experts.

And by using Git for version control and GitHub to host our documentation repositories, we can iterate our documentation alongside our products and make sure they stay in sync. This means we can:

• be sure that user always see the most up to date version of the documentation
• track every change
• revert to earlier versions if needed
• work on changes independently before merging into the master content
• backup and restore our content

GitHub’s comment threads allow the team to discuss possible changes before merging and updating the live documentation.

References