Skip to main content

docs-as-code

Title:
RFC001 - Docs as Code for Internal Technical Documentation

Author:
Will Salt

Date:
26/11/2025

Status:
Draft

1. Overview​

Problem Statement:
Currently we do not have a place to document engineering practices, processes or the general workings of the system. We should be continually documenting such things and evolving the documentation as we go, collaborating and improving it. Whilst we have notion and confluence these are unused. Using these tools can lead to creating un-audited, reviewed often ugly documentation. Using such platforms works, but often gets very messy, outdated, and duplicated.

Proposed Solution:
Adopt a "Docs as Code" approach for managing internal engineering documentation. This method treats documentation with the same rigor as code, leveraging version control, peer reviews, continuous integration, and automated testing. There are many people who already have adopted docs as code internally, there is a great article from the home office which highlight why it is so valuable.

2. Motivation​

Effective documentation is crucial for maintaining high-quality software. Traditional documentation methods often lead to outdated, inconsistent, and hard-to-maintain documents. Often people will create pages in confluence or notion, and they get lost in the noise. There is no way to peer review these documents, or easily socialise them to others. The Docs as Code approach addresses these issues by integrating documentation into the development workflow. Treating documentation like code means that you can use the same workflows and tooling to write and improve your documentation.

Benefits​

1. Version Control​

Using version control systems (VCS) like Git ensures that documentation changes are tracked, reviewed, and can be rolled back if necessary. This leads to more accurate and reliable documentation.

2. Collaboration​

Docs as Code forces you to seek reviews from others like you would with code, through pull requests. Here people can help improve them, point out duplication, but also increase awareness of how something works, or that the documentation even exists. In turn this should create cleaner more concise up to date documentation.

3. Automation​

Continuous Integration (CI) pipelines can be used to automate the building, testing, and deployment of documentation. This reduces manual effort and ensures that documentation is always up-to-date. We can publish preview branches to cloudflare pages to preview the docs, before we merge these changes in.

Examples of Key Adopters​

Shopify Shopify uses Hugo, a static site generator, along with GitHub Actions for CI/CD to manage their documentation. They have detailed their documentation practices and tools in various engineering blog posts.

Grab

Check out their blog post here

Spotify Spotify uses tech docs to manage their internal documentation, theres a great blog post here. They use Backstage, an open platform for building developer portals, which they have open-sourced to surface these docs. Backstage helps Spotify engineers to manage their services and documentation efficiently. More details can be found in their blog post. This is a bit advanced for us, but docs as code would let us move towards it in future.

3. Detailed Design​

Architecture/Design Details:

Tools​

  • Version Control: Git
  • CI/CD: GitHub Actions
  • Static Site Generators: Hugo or Docusaurus
  • Linters: Markdownlint for markdown

Process​

  1. Writing: Use Markdown for writing documentation.
  2. Review: Implement a pull request workflow for reviewing changes.
  3. CI/CD: Deploy branch previews and main via cloudflare pages.
  4. Testing: Integrate linters and other tools to ensure quality and consistency.

Implementation Plan:
There are two PRs #1 and #2 which show how these could be implemented with cloudflare zero trust and either hugo docsy or docusaurus.

4. Alternatives Considered​

Mkdocs - github page This is a lot more basic and is used less for internal engineering documentation. I have a demo of this as well if people want to see it though, i have used this before.

Github Pages for hosting - You have to push the dist files to a branch and it is very clunky, you also have to be a member of github to see these private pages. Cloudflare pages is a lot more flexible and we can open it up to groups of users in our google directory through SSO.

5. Drawbacks​

  • There is a process to modify documentation and you must get it reviewed.
  • There is a setup overhead and it is not straightforwards in some cases.

6. Dependencies​

None.

7. Impact​

None.

8. Unresolved Questions​

None.

9. Timeline​

1 day.