Outdated docs are worse than no docs

A team with no documentation knows it has no documentation. Engineers ask questions, interrupt colleagues, and reconstruct context verbally. It's inefficient but at least everyone knows the situation.

A team with outdated documentation has a different problem. The docs exist, they look authoritative, and they're wrong. An engineer follows the setup guide and wastes an afternoon because the guide references a dependency that was replaced three months ago. Another engineer reads the architecture overview, makes a design decision based on it, and discovers during code review that the overview describes a system that was restructured in the last quarter.

After two or three of these experiences, the engineer stops trusting the docs. They go back to asking people directly, which is what they would have done if no docs existed. But now the team is paying the cost of maintaining docs that nobody reads, on top of the cost of the verbal knowledge transfer that the docs were supposed to eliminate.

This is the documentation paradox in its most harmful form: the investment in documentation has produced negative returns because the docs actively misdirect rather than simply being absent.

How docs go stale

Documentation doesn't rot because engineers are careless. It rots because every merged PR makes the existing docs slightly less accurate, and the correction work is never prioritised.

A refactor changes how two services communicate. The engineer updates the code, writes tests, gets the PR reviewed and merged. Updating the three wiki pages that describe the old communication pattern isn't part of the PR checklist and isn't part of the sprint. Nobody assigns it because nobody is tracking which docs are affected by which code changes. The wiki pages sit there, describing a system that no longer exists, waiting for someone to follow them and fail.

The rate of staleness correlates directly with shipping speed. The faster you ship, the faster your docs go out of date, which means the teams that most need reliable documentation (fast-moving, rapidly evolving codebases) are the ones whose docs rot fastest.

The trust problem

Trust in documentation, once lost, is extremely difficult to rebuild. It takes dozens of accurate, useful doc consultations to build the habit of checking docs first. It takes one or two misleading experiences to break it.

Once an engineering team has collectively learned that the docs can't be trusted, the docs become invisible. New hires are told informally that the wiki is "mostly outdated" and that they should ask instead of reading. The docs still exist, still appear in search results, still look official, but they've been functionally abandoned. Every hour that was spent writing them has been wasted.

The only documentation that avoids this problem is documentation that stays current automatically. Self-writing docs generated from live engineering activity (PRs, Slack threads, meeting recordings) update as the underlying activity changes. The docs reflect reality because they're written from reality rather than maintained alongside it.

The audit question

There's a simple test for whether your docs have this problem. Pick a random wiki page or architecture doc that was last updated more than three months ago. Read it. Then ask the engineer who currently owns that system whether the doc is still accurate.

In most teams, the answer is some version of "parts of it are right but some of the details have changed." Those details are the ones that will waste the next engineer's afternoon.

Frequently asked questions

Should we just delete stale docs? Deleting clearly outdated docs is better than leaving them to misdirect people. But the better solution is preventing staleness rather than cleaning up after it. Docs that write themselves from live sources don't go stale in the same way because they update as the underlying activity changes.

How do we know which docs are stale? Track when docs were last updated relative to when the systems they describe were last changed. If a doc about the authentication flow was last edited in January and the auth service has had 40 PRs since then, the doc is almost certainly stale.

Is it worth maintaining docs manually if we ship fast? The faster you ship, the faster manual docs rot, which means the ROI of manual documentation decreases as shipping speed increases. For fast-moving teams, automated documentation is the only approach that keeps pace.

Related reading: The documentation paradox, Documentation debt, Why engineers hate writing docs. Related pages: Self-writing docs, For engineering teams.