Technical debt has a perception problem. It gets discussed as a future concern — something to address when the product is bigger, the team is larger, there is finally a quiet quarter. There is never a quiet quarter.
The debt is accruing right now, in the absence of documentation, in the architectural decisions that exist only in the memory of whoever made them, in the code that has never been explained to anyone. The cost is not deferred. It is distributed invisibly across every hour your team spends working in the codebase.
What the cost actually looks like
Here is a practical exercise. Count the hours your team spent last month answering questions about the codebase. Questions from new engineers trying to become productive. Questions from product managers trying to understand what is technically possible. Questions from whoever was on-call trying to understand what “do not touch this” means and why it is in a comment with no further context.
Then count the bugs that came from misunderstood assumptions. The incidents where someone changed something they did not know was load-bearing. The slow outages — the ones that were slow because the engineer responding had to read unfamiliar code under pressure to understand the system they were supposed to be operating.
That is the cost of documentation debt. It is not hypothetical. It is already on your team’s calendar, disguised as something else.
What good documentation actually looks like
Good documentation is not a README. A README tells you how to start the development server. Good documentation tells you why the system exists in its current form, what invariants it depends on, what will happen if the wrong thing changes, and what the team learned from the decisions they made.
The documents that actually matter are these:
Architecture decision records. Short documents — half a page — that record what was decided, why, and what the alternatives were. They do not need to be formal. They need to exist and be findable. The question they answer is not “what does this do” but “why does it do it this way.”
Runbooks. If someone is paged at 2am for a service you own, what do they do? What are the alerts? What do they mean? What is the correct response to each one? If the answer to any of those questions is “ask the person who built it,” you have encoded a human dependency into your operational process. That dependency will eventually be unavailable.
Onboarding documentation. Track how long it takes a new engineer to make their first meaningful contribution. If the answer is more than two weeks, the gap is almost always documentation — not capability.
The handoff test
We apply a heuristic we call the handoff test to everything we ship: if the primary engineer on this service were unavailable for two weeks with no notice, how long would it take another engineer to be fully effective?
Less than a week is good. One to two weeks is acceptable. More than two weeks means the documentation is insufficient, regardless of what the README says, regardless of how clean the code is.
We apply this test not because it makes builds slower — it adds very little time when done continuously rather than retrospectively — but because we have inherited enough poorly documented codebases to know exactly what the failure mode looks like. We have seen engineering teams paralysed by a system only one person understands. We have seen acquisitions stall because the acquirer could not assess what they were buying. We have seen founders unable to hire because the codebase was too opaque for new engineers to join.
The compounding problem
The reason documentation debt compounds is that it becomes harder to write the longer you wait. The engineer who made a decision six months ago has forgotten the alternatives they considered. The context that seemed obvious at the time has evaporated. What should be a fifteen-minute document becomes a three-hour archaeology project, and so it keeps getting deferred.
The correct time to document a decision is immediately after making it, while the reasoning is still accessible. The correct time to write a runbook is before the first incident, not during it. The correct time to update onboarding documentation is when a new engineer finds something that was not covered.
None of this is glamorous. It rarely appears on a roadmap. It does not ship a feature. But it is what separates a codebase that an organisation owns from one that owns the organisation.