Skip to content
Saif Rashed

Treat Your Documentation Like Code

4 August, 2026

Cover images

Attention is one of a developer’s most valuable resources. Focus drives progress, and every interruption comes at a cost.

Researcher Sophie Leroy calls this cost “attention residue.” In her 2009 paper, Why Is It So Hard to Do My Work?, she explains how part of our attention remains on a previous task after switching to another. For developers, every context switch means reorienting to a new task, and then reorienting again when returning to the original one.

Documentation often creates exactly this problem.

Traditionally, documentation has lived separately from code in tools such as Microsoft Word, Google Docs, or Confluence. This disconnect makes documentation easier to neglect and forces developers to leave their development environment to update it.

What if we treat documentation like code?

Docs-as-code applies software development practices to documentation. Documentation is stored alongside the code and managed with the same tools and workflows, including:

  • Version control
  • Pull requests and code reviews
  • Continuous integration
  • Automated publishing

Developers can update code and documentation in the same commit without leaving their IDE. Because both share a repository and review process, documentation is more likely to remain aligned with the software. It also leads to less context switching, a single source of truth, perfect versioning and immutable audit trails.

Spotify has used a similar approach for years. Engineers write documentation in Markdown alongside their code, generate documentation sites with MkDocs during CI, and make them available centrally through Backstage. Product manager Gary Nieman explains the workflow in this presentation.

There are trade-offs

Docs-as-code is not perfect. Markdown may feel less intuitive than a visual editor, and Git-based workflows can be a barrier for non-technical contributors.

AI tools such as GitHub Copilot, Cursor, and ChatGPT are reducing that barrier. They can generate Markdown, improve formatting, and suggest clearer wording. Plain-text documentation is also easy to search, index, and analyze using IDEs and AI tools.

Taking a hybrid approach often works best:

  • Keep core technical documentation alongside the code.
  • Use traditional tools for supplementary or user-facing content when visual editing and broad collaboration matter more.

The goal is not to force every document into Git. It is to reduce context switching, keep technical documentation accurate, and make documentation part of development, and not something we do later, supposedly.