Docs & Code Guide

Documentation debt: a register, a number in hours, and a delete-first paydown

Documentation debt is the stock of docs that are wrong, unowned, or missing, and like technical debt it charges interest: support questions, slow onboarding, incident minutes lost to a misleading page. Teams manage tech debt with a register and a paydown plan, then treat doc debt as a vague guilt. Give it the same machinery: itemize it, price it in hours, and pay it down in an order that starts with deletion.

Try it free
7 min readFor the engineer who inherited a wiki nobody trusts

See it as a diagram

Everything below, as a diagram you can edit. Describe yours and see it in seconds.

200/2000• 3 credits left
Try:

No account needed · Editable canvas, not a picture

Treat it as a register, not a feeling

Documentation debt is manageable the moment it becomes a list. The register needs one row per known-bad or missing doc and a handful of columns: the page, its owner or the fact that it has none, when it was last verified, and the cost of wrongness, meaning what happens to the person who follows it today. That last column is the one that ranks the work, because a wrong failover step and a wrong lunch-spot recommendation are both stale docs.

Keep the register where engineers already look, a repo file or a pinned wiki page, and review it monthly for fifteen minutes. The review is not a writing session; it is triage: rows get a decision, delete, redirect, generate, or fix, and a name. A register without decisions is just an inventory of guilt.

| Page                    | Owner | Last verified | Cost of wrongness                       | Decision |
| ----------------------- | ----- | ------------- | --------------------------------------- | -------- |
| wiki/payments-oncall    | dana  | 2026-01-14    | Wrong failover steps during a Sev1      | fix now  |
| wiki/etl-setup-2023     | none  | 2024-11-02    | Sends new hires down a removed path     | delete   |
| wiki/platform-overview  | mike  | 2025-06-20    | Diagram omits two services, misleads    | generate |
| wiki/deploy-guide       | none  | 2025-09-30    | Duplicates the newer runbook, conflicts | redirect |

Quantify it in hours

Three numbers are countable this week and convert directly to hours. First, pages past their review SLA: if docs carry a last-verified date, this is a script over front matter; the count times a realistic verification effort is your backlog in hours. Second, unowned pages: no owner means no one is accountable for wrongness, and the count is a proxy for how much of the wiki is abandoned in place.

Third, and most persuasive to whoever holds the budget: support questions caused by missing or wrong docs. For two weeks, tag every Slack question a doc should have answered, multiply by the minutes each answer took, and annualize. The result is the interest payment, in senior-engineer hours per month, and it turns the docs conversation from aesthetics into arithmetic. The cost of outdated documentation develops the full cost model, including the incident-risk term that dwarfs the rest.

Pay it down delete-first

The paydown order matters more than the effort invested, and the correct order starts with the cheapest action that removes the most harm: delete. A wrong page is worse than a missing one, because the missing page sends readers to a person while the wrong page sends them, confident, in the wrong direction. Delete every row whose content is wrong and unowned; nobody defends these pages once someone finally proposes it.

Redirect comes second: merge duplicates so the surviving page concentrates whatever maintenance attention exists. Generate comes third and is where the payoff concentrates, covered below. Full rewrites come last, reserved for prose that earns human authorship: onboarding narratives, decision records, the why behind the system.

Fixing everything, the intuitive plan, is the losing move. Writing capacity is a few pages a month; debt accrues faster; the register grows while the team burns out on rewrites of pages nobody reads, and everyone concludes documentation is hopeless. Delete-first shrinks the register on day one and spends scarce writing hours only where prose is the right medium.

The generate step is where accrual stops

Deleting and fixing address the stock of debt; generation addresses the flow. A rewritten page starts decaying the day it ships. A generated projection, a diagram drawn from the repository, a schema doc from the database, a CLI reference from --help output, tracks its source instead, so the same class of debt does not re-accrue.

Architecture pages are the highest-value conversion because hand-drawn system diagrams rot silently and mislead the readers least equipped to notice. Replace the pasted export with a live embed URL so every page shows the current version within minutes of an edit, and put the regeneration one command away with an MCP-connected agent that redraws from the repo. Two honest caveats: the live embed requires the project to be shared public, which rules out some confidential architectures, and Datadef does not watch the repository, so the regeneration still needs its trigger, a CI job or a review habit.

Intake for the register

If you do not yet know what your debt is, the documentation audit checklist is the intake pass that populates the register, and a documentation SLA keeps new rows from accumulating unnoticed.

FAQ

What is documentation debt?

Documentation debt is the accumulated stock of documentation that is wrong, unowned, duplicated, or missing, weighed by the harm it causes. Like technical debt it charges interest: repeated support questions, slower onboarding, and incident minutes lost to misleading pages. It is best managed the same way, with an itemized register, owners, and a deliberate paydown order.

How do you measure documentation debt?

Count three things: pages past their review SLA, pages with no owner, and support questions that a doc should have answered, tagged over a sample fortnight and multiplied by minutes per answer. The first two size the backlog; the third prices the monthly interest in engineer hours, which is the number that survives a budget conversation.

Should we fix outdated docs or delete them?

Delete first. A wrong page is worse than a missing one because it misleads with confidence, and deletion costs minutes while a rewrite costs hours. The paydown order that works: delete wrong and unowned pages, redirect duplicates into survivors, generate whatever can be derived from source such as architecture diagrams and CLI references, and rewrite only the prose that earns human authorship.

How is documentation debt different from technical debt?

The structure is the same, principal and interest, but documentation debt is invisible in the tools engineers watch: nothing fails a build when a wiki page goes wrong, and readers rarely report errors because they cannot tell wrong from current. That invisibility is why it needs an explicit register with last-verified dates, where tech debt at least announces itself through friction in the code.

How do we stop accruing new documentation debt?

Move the volatile content onto generated projections: diagrams regenerated from the repository via an agent, references produced from code, embeds that follow their source within minutes of an edit. Then put the remaining prose under a review SLA with named owners. Generated content cannot drift from its source in the way hand-maintained copies do, so the debt-producing surface shrinks to the prose.