Documentation drift

How drift happens

Drift is not a single event. It accumulates one merge at a time, and almost always through the same four openings:

• Renamed or removed surface. A flag, endpoint, or configuration key changes name. The code compiles, the tests pass, and the page describing the old name is now quietly wrong.
• Changed defaults. Nothing in the documentation is factually incorrect, but the behaviour a reader gets when they follow it no longer matches what the page implies.
• New surface, undocumented. The feature ships. The page that should describe it is a ticket in someone's backlog.
• Examples that no longer run. The most damaging kind, because a copied example that fails is the moment a reader stops trusting the whole doc set.

Each of these is small. None is worth blocking a release over. That's precisely why drift compounds — every individual instance is beneath the threshold at which anyone intervenes.

Why it's a structural problem, not a discipline problem

The standard response to drift is a process fix: a docs checkbox in the pull request template, a style guide, a quarterly documentation sprint, a rotating owner. These work for a few weeks and then decay, and they decay for a reason that has nothing to do with how conscientious the team is.

Code and documentation live on different update cycles and have different failure modes. Wrong code fails loudly — a test breaks, an alert fires, a customer opens an incident. Wrong documentation fails silently. Nothing in the system notices, and the only signal is a support ticket weeks later that nobody traces back to a page.

Any fix that relies on a person remembering to update a second artifact, at the moment they are trying to ship a first one, is fighting that asymmetry with willpower. Willpower loses on a long enough timeline.

What drift actually costs

Documentation debt never triggers an incident, so it never makes the roadmap. The cost shows up displaced into other budgets:

• Support load. Repeat tier-1 questions that a correct page would have answered.
• Onboarding time. New engineers learn to distrust the docs early, then interrupt senior engineers instead — which is the expensive path.
• Refactoring hesitancy. When nobody is confident what is documented, changing it feels riskier than it is.
• Trust, which is the compounding one. Readers do not evaluate pages individually. A handful of wrong pages devalues every correct page around them.

How teams close the gap

Approaches that hold tend to share one property: the documentation is derived from the code rather than maintained alongside it. That takes a few forms —

• Generate reference material from source. Signatures, parameters, and types come from the thing they describe, so they cannot disagree with it.
• Execute the examples. Treat a documented command or API call as a test. If it doesn't behave as written, that's a failure with a stack trace, not a silent inaccuracy.
• Measure coverage. You can't manage drift you can't see. Knowing which parts of the public surface have no corresponding documentation turns a vague worry into a tracked number.
• Regenerate on every release. Remove the human step entirely, and the update cycles stop diverging.

Git2Docs takes the last of these: documentation is synthesised from the repository and resynced on every push, with a runtime validator that exercises documented CLI commands and API calls against the live deployment and reports the ones that don't match.