Glossary
Documentation debt
Definition
Documentation debt is the accumulated cost of documentation work that was deferred — content never written, never updated, or never verified — which gets repaid later through support load, slower onboarding and implementations built against wrong information.
Debt is not drift
The two terms are often used interchangeably and describe different things.
Drift is the gap: the distance between what the documentation says and what the code does. It is a measurement, taken at a point in time.
Debt is the obligation: the accumulated cost of not having closed that gap. It is a liability that compounds.
A team can measure drift on Monday and have a number. The debt is what that number has been costing since it opened, and what it will keep costing until someone pays it down. Drift tells you how far off you are; debt tells you what being off has cost.
Why it behaves differently from technical debt
Technical debt is visible to the people carrying it. The build is slow, the module is painful to change, the workaround has a name. Engineers feel it daily, which is how it gets onto a roadmap.
Documentation debt is invisible to the team that owns it, because the people paying it are somewhere else. Support answers the same question for the fourth time. A new hire loses a day. A customer's engineer builds against a parameter that no longer exists. None of that reaches the team that could fix it, and when it does, it arrives as a support ticket rather than as a defect.
That asymmetry explains the behaviour that frustrates everyone: documentation debt is widely acknowledged and rarely prioritised. It never triggers an incident, so it never competes successfully for a sprint.
Where it accumulates
Four openings account for most of it:
- The feature that shipped under deadline, where docs were the line item cut
- The parameter added to an existing endpoint, too small to prompt a documentation review
- The behaviour change that looked internal, where nobody thought to check what the docs claimed
- The deprecation nobody finished, leaving the old documentation in place beside the new
None of these fails a build. Nothing stops the merge.
Making it visible
Debt that cannot be seen cannot be prioritised, and the fix is measurement rather than discipline.
A count of documentation claims that do not match the code turns a vague obligation into a number that moves. Coverage turns "the docs are patchy" into a percentage with a list of gaps behind it. Neither is interesting as a vanity metric — they are useful because they make an invisible liability behave like a visible one, which is the only thing that has ever got documentation work scheduled.
Go deeper
Questions people ask
Is documentation debt a type of technical debt?
It is usually classified as one, but it behaves differently in the way that matters: technical debt is felt by the team carrying it, documentation debt is paid by people outside the team. That is why it rarely gets prioritised on its own merits.
How do you quantify documentation debt?
Through its components — coverage, for what is missing, and a count of inaccurate claims, for what is wrong. A single composite number is less useful than two that each point at a work queue.
Does generating documentation from code eliminate it?
It removes the kind created by deferral, since nothing waits to be written. It does not remove design rationale that was never recorded anywhere — code expresses what the system does, not why it was built that way.