Documentation Rot

What It Is

Documentation rot is the gradual divergence between documentation and the system it is supposed to describe. The code, APIs, configuration, and processes evolve, but the documentation does not keep pace. What was once accurate becomes stale, then misleading, and eventually so unreliable that the team stops trusting any of it. The documentation still exists, but it no longer reflects reality.

Rot is insidious because outdated documentation can be worse than none at all: people follow it confidently and are led astray.

Why It Happens

• Docs separated from code. When documentation lives far from the code it describes, updating it is an easy step to skip.
• No ownership. Nobody is responsible for keeping a given document current, so it ages untended.
• Time pressure. Updating docs is the first task dropped when deadlines loom.
• No update trigger. Changes ship without any check that related documentation changed too.

Why It Hurts

Stale documentation gives misleading guidance, sending engineers down wrong paths and wasting hours of debugging. Once people are burned by inaccurate docs, they stop trusting the entire corpus, which destroys the value of even the correct parts. Onboarding suffers most, as newcomers cannot tell which instructions still work. Effort spent writing documentation is wasted if it is not maintained, and the team falls back on tribal knowledge instead.

Warning Signs

• Setup instructions or examples no longer work.
• Documentation references removed features, old APIs, or renamed components.
• Team members say "don't trust the docs, ask someone."
• Pull requests change behavior but never touch the related documentation.

Better Alternatives

• Docs as code. Keep documentation in version control next to the code, reviewed in the same pull requests.
• Executable documentation. Test examples and generate reference material from the source so it cannot drift.
• Single source of truth. Avoid duplicating the same information in places that fall out of sync.
• Documentation ownership. Assign clear owners and a review cadence for important documents.

How to Refactor Out of It

Move documentation close to the code and review it in the same pull request, so changing behavior without updating docs becomes visible. Make examples executable — run them in CI — and generate API references from the source so they cannot lie. Eliminate duplicate copies in favor of a single source of truth. Assign ownership and a periodic review for the documents that matter most, and prune anything no longer worth maintaining. Treat documentation as part of the definition of done, not an afterthought, so it stays current by default rather than rotting by neglect.