Documentation That Doesn't Rot: The Practice of Treating Docs as Code

There's a documentation anti-pattern so common it's almost universal: the README that describes how to set up the project based on how it was set up in 2021, the API documentation that describes the response format before the refactor last spring, the architecture diagram that shows the microservices decomposition before the consolidation. Engineers learn quickly not to trust documentation in most codebases, and that learned distrust means they don't read it even when it's accurate — which further reduces the motivation to keep it accurate.

This is a structural problem, not a discipline problem. Documentation that lives in a wiki or a separate repository is decoupled from the code it describes. When the code changes, updating the documentation is a separate step that requires remembering it exists, finding the right place to update it, and allocating time that's never on the critical path. The documentation drifts. The documentation becomes unreliable. The documentation becomes unused.

Documentation That Lives With the Code

The structural solution is docs-as-code: documentation that lives in the same repository as the code it describes, reviewed in the same pull request, and updated as a required part of any change that affects documented behavior. This doesn't mean all documentation lives in code comments — it means that the process for changing documentation is the same process as changing code, with the same review requirements and the same versioning.

When a PR changes the behavior of a public API endpoint, it should include updates to the API documentation file in the same diff. When a PR changes the setup process, it should update the README in the same diff. The code reviewer sees both changes simultaneously and can verify that the documentation accurately reflects the code change. If the documentation isn't updated, the review can block the merge — the same way a missing test blocks a merge in teams with test coverage requirements.

The Three Types of Documentation Worth Maintaining

Reference documentation describes what exists: API endpoints and their parameters, configuration options and their effects, environment variables and their purpose. This is the documentation that engineers consult when they need to know how to use something. It should be generated from code where possible (OpenAPI specs from annotated routes, TypeDoc from typed function signatures) to make automatic accuracy the default.

Explanatory documentation describes why decisions were made: the architecture decision records, the technical design documents, the post-incident analyses. This documentation has a different relationship to code — it doesn't need to be updated when the code changes, because it records historical decisions. But it does need to be created at the time decisions are made, which is the step most teams skip.

Tutorial documentation guides someone through accomplishing a specific task: getting the project running locally, deploying to a new environment, implementing a specific integration pattern. This documentation rots fastest because it describes a sequence of actions that must work correctly in order. Testing tutorial documentation regularly — having someone follow it from scratch — is the only reliable way to keep it accurate.

Making Documentation Review Standard

Adding "documentation updated" to your PR template as an explicit checkbox — with a note that applies if the change affects documented behavior — makes documentation updates part of the submission discipline rather than something that gets remembered occasionally. It takes thirty seconds per PR and produces a documentation culture where accuracy is maintained by process rather than by individual heroics.