Documentation Debt Compounds Faster Than Code Debt

Bad code sits there being bad until someone touches it. It doesn't actively mislead anyone — it's just unpleasant to work with. Bad documentation is worse, because it doesn't sit passively. It actively tells the next person something false, and they act on it with full confidence that it's true.

I watched a new engineer at a client spend two full days debugging a tagging issue because the setup doc described an architecture that had been replaced eight months earlier. The doc wasn't ambiguous or incomplete — it was confidently, specifically wrong, which is far more dangerous than no documentation at all. No doc would have sent them straight to the actual code. The wrong doc sent them in the opposite direction with total confidence.

Why it compounds specifically

Code debt is mostly contained to whoever has to work in that file. Documentation debt spreads with every person who reads it, and each of them makes decisions based on it, and some of those decisions get documented elsewhere, citing the original wrong doc as a source. The error doesn't just persist — it replicates into other documents, other decisions, other people's mental models, each generation a little further from anyone realizing the root cause was one stale paragraph.

Bad code wastes the time of whoever opens the file. Bad documentation wastes the time of everyone who trusts it, and they don't find out it was wrong until after they've acted on it.

What's actually worked to slow it down

• Treating documentation updates as part of the definition of done for any change, not a follow-up task that gets deprioritized
• Dating every doc visibly, so staleness is at least detectable even when it isn't fixed yet
• Deleting docs aggressively when a system changes enough that updating feels like rewriting — a missing doc is safer than a confidently wrong one
• A recurring 'does this still match reality' pass on critical docs, scheduled like any other maintenance task instead of left to chance

I've started treating a stale doc as actively more urgent to fix than a messy function, because the messy function only costs time when someone opens it. The stale doc costs time the moment someone trusts it, and trust is the default assumption for anything labeled documentation.