Documentation Drift Explained

Part 1 was about the rules that were never written down. This part is about a subtler and more common problem: the rules that were written down, and then quietly stopped being true. If tribal knowledge is the documentation you don’t have, documentation drift is the documentation you can’t trust — and it’s the reason “we have documentation” almost never means “we know what our system does.”

What drift is

Documentation drift is the gradual divergence between what the documentation describes and what the system actually does. The architecture diagram shows a service that was merged two reorganizations ago. The API reference lists a parameter that was deprecated last year. The runbook’s recovery steps point at a server that no longer exists. None of these were wrong when written. They drifted.

The word matters. Docs don’t usually break — that would be loud, and someone would fix it. They drift: each release moves the system a little further from its description, no single change large enough to notice, until the cumulative gap is enormous and no one can say where the documentation is right and where it lies.

Why it’s structural, not careless

It is easy to blame drift on lazy engineers who don’t update the docs. That diagnosis is both unfair and useless, because it misreads the cause. Drift is the product of an asymmetry built into how software is made.

Changing the code is mandatory — the feature doesn’t ship otherwise. Updating the document that described that code is optional — nothing fails if you skip it, no test goes red, no deploy is blocked. Put a mandatory task and an optional one under the same deadline and the optional one loses, every time, to engineers who are behaving entirely reasonably. The doc and the code it describes live in separate places and are maintained by separate acts of will, and only one of those acts is enforced.

So drift isn’t a discipline problem you can solve by asking people to try harder. It is the default outcome of any process where the description of the code is maintained apart from the code. The surprising thing would be documentation that didn’t drift.

The kinds of drift, and why some are worse

Not all drift is equally dangerous, and it helps to separate the kinds — because the order of severity is the opposite of the order of visibility.

• Stale references — names, paths, versions, and diagrams that point at things that have moved or been renamed. Annoying, usually obvious, and the least costly: a reader notices the server doesn’t exist and goes looking for the real one.
• Incomplete coverage — documentation that stopped keeping up, so newer features and recent changes simply aren’t described. This reads as a gap, which at least signals “ask someone.” It’s the drift closest to plain tribal knowledge.
• Contradicted behavior — documentation that confidently describes how something works, when the code now does something else. This is the worst kind, and the hardest to spot, because nothing about the page looks wrong. The reader follows it, builds on it, and inherits a decision the system reversed years ago.

The cruel part is that the most dangerous kind is the most authoritative-looking. A blank or a broken link warns you. A fluent, well-formatted, completely wrong description does not. The documentation you should trust least is often the documentation that reads best, because polish is a property of when it was written, not of whether it’s still true.

The two faces of not knowing your system

Tribal knowledge and documentation drift are the same problem wearing two masks. Both end at the same place — a team that doesn’t actually know what its system does — but they get there differently, and the drifted version is the more dangerous of the two.

	Tribal knowledge	Documentation drift
What’s wrong	The rule was never written down	The rule was written down, then changed
What you see	A blank — a gap you may notice	A confident answer that’s quietly false
Where the truth lives	In people’s heads	In the code, not the doc
Why it’s dangerous	Lost when people leave	Trusted because it exists

A blank page at least announces itself; a reader knows to go ask someone. A drifted document does the opposite — it hands the reader a plausible, authoritative-looking answer that happens to be wrong, and the reader builds on it. The most expensive bugs in a modernization often trace back not to missing documentation but to documentation that was confidently followed and turned out to have drifted years ago.

Why this sinks modernization

Most modernization programs begin by gathering the existing documentation, and most of that documentation has drifted. Build the new system against the drifted docs and you faithfully reproduce a system that hasn’t existed for years — while the actual current behavior, the thing real users depend on, gets silently dropped.

This is why experienced teams treat existing documentation as a hypothesis, not a source. The diagrams and specs are useful as a starting map and a record of intent, but the question they raise — “is this still true?” — can only be answered against the running system. The single source of truth for what a system does today is the code that is doing it, plus the production behavior that code produces. Everything else is a claim awaiting verification. This is the same logic behind parity validation: you hold the new system to what the legacy actually does, never to what a document says it should.

What drifted documentation is still good for

Drifted documentation isn’t worthless, and discarding it wholesale is its own mistake. Old docs capture intent — what the system was meant to do, the problem a subsystem was built to solve — and intent is exactly the context the code can’t give you on its own. The code tells you a field is validated a certain way; a five-year-old design note might tell you why, and that why can be the difference between a load-bearing rule and an accident safe to drop. So the right move is neither to trust the docs nor to bin them. It is to use them as evidence of intent while recovering current behavior from the code — and to reconcile the two deliberately, treating every disagreement between them as a question to answer rather than a side to pick.

Where this leads

Parts 1 and 2 have established the problem from two directions: knowledge that was never recorded, and records that drifted from the truth. The natural next question is so what — what does it actually cost a business when this understanding is lost, and why is the bill so often invisible until it comes due all at once. Part 3, The Risk of Lost Institutional Knowledge, puts numbers and consequences to the problem these two parts defined.