Half the Debt, None of the Dashboard: What Your Tech Debt Tracker Is Getting Wrong

Every engineering org has some version of a tech debt tracker. Maybe it lives in Jira, maybe it's a Google Sheet someone built in 2021 and still technically maintains, maybe it's just a Slack channel called #debt-we-should-fix-someday. Whatever the format, these trackers share a common blind spot: they measure code, and almost nothing else.

Deprecated dependencies? Tracked. Monolithic components that should've been broken apart two years ago? Tracked. Unit test coverage sitting at a shameful 34%? Tracked, and probably the subject of at least one tense quarterly planning meeting.

But documentation debt? The outdated setup guide that still references a tool you sunset in 2022? The API reference that hasn't been touched since the endpoint signatures changed? The architecture decision record that describes a system you completely rebuilt? None of that shows up in the dashboard. And yet it's costing you just as much—sometimes more.

What Documentation Debt Actually Looks Like

Before you can measure something, you need a clear picture of what you're measuring. Documentation debt isn't just "old docs." It's a spectrum of compounding liabilities:

Stale accuracy debt is the most obvious kind—content that used to be correct and no longer is. A deployment guide that references a deprecated CI pipeline. A configuration reference that predates your infrastructure migration. This type of debt is dangerous because it actively misleads people who trust it.

Coverage debt is the gap between what your system does and what's documented. New features shipped without accompanying docs. Internal APIs that exist only in someone's head (or worse, only in the head of someone who left six months ago). This debt doesn't mislead—it just leaves people with nothing to work from at all.

Findability debt is subtler and arguably more frustrating. The documentation exists, but it's scattered across four tools, duplicated in three places with slightly different versions, and impossible to navigate without already knowing what you're looking for. The information is technically available; it's just not usable.

Structural debt happens when your docs grow organically without a coherent information architecture. What starts as a few helpful pages becomes an unmaintained sprawl where nobody's confident they've found the authoritative source on anything.

Each of these categories compounds differently, but they all share one trait: the longer you let them run, the more expensive they get to fix.

Modeling the Hidden Cost

Here's where most documentation debt conversations stall. Somebody raises it in a planning meeting, a few people nod, and then nothing happens because there's no number attached to it. Code debt has proxies—story point overhead, regression rates, deployment frequency. Doc debt feels squishy by comparison.

It doesn't have to be.

Start with onboarding time. How long does it take a new engineer to become independently productive on your codebase? Industry benchmarks vary, but most teams land somewhere between 30 and 90 days for full productivity. Now ask: how much of that timeline is friction from documentation gaps versus actual ramp-up complexity? If you've done exit interviews or onboarding retrospectives, you probably have anecdotal data here. Formalize it. If a week of onboarding time is attributable to doc gaps, and you're hiring 10 engineers a year at a fully loaded cost of $200K each, that's roughly $400K in productivity loss annually—from documentation debt alone.

Next, look at interrupt-driven knowledge transfer. Count how often senior engineers get pulled into Slack threads, meetings, or ad hoc walkthroughs to explain things that should be documented. This is one of the most insidious costs of doc debt because it doesn't just waste the time of the person asking—it interrupts the person answering. Research on developer productivity consistently shows that deep work interruptions cost far more than the interruption itself. A five-minute Slack answer can derail an hour of focused engineering work.

Finally, consider incident resolution time. When something breaks at 2am, how much time does your on-call engineer spend hunting for runbooks, piecing together context from old PRs, and reverse-engineering undocumented behavior? Shaving 20 minutes off your mean time to resolution doesn't sound dramatic until you multiply it across a year's worth of incidents.

None of these numbers are precise. But they're real, and they're estimable. The goal isn't a perfectly accurate figure—it's a credible one that can anchor a business case.

Building the Case to Pay It Down

Once you have rough numbers, the conversation shifts from "we should probably fix our docs" to "here's what it's costing us not to."

The most effective framing for engineering leadership isn't moral ("good docs are the right thing to do") or aesthetic ("our docs are embarrassing"). It's economic. Documentation debt has a carrying cost, just like financial debt. Every sprint you don't address it, the interest compounds in the form of slower onboarding, more interruptions, longer incident resolution, and—eventually—turnover from engineers who are tired of working in a system they can never fully understand.

A few tactical moves that help make this real:

Run a doc debt audit with a scoring rubric. Assign each piece of documentation a score based on accuracy, coverage, and findability. Aggregate the scores. Now you have a baseline you can actually track over time. It doesn't need to be perfect—it needs to be consistent.

Tie doc debt to velocity metrics you already track. If your team measures sprint velocity, look for correlations between documentation gaps and story point overruns. Teams often discover that the tickets with the most "unexpected complexity" are the ones touching the least-documented parts of the system.

Treat doc debt like a first-class backlog item. Not a separate backlog that lives in a wiki nobody reads—actual tickets in the same system your team uses for everything else, with priority rankings and owners. When doc debt competes for attention alongside feature work, it at least has a fighting chance.

The Compounding Problem You Can Actually Control

Here's the thing about documentation debt that makes it different from most code debt: a lot of it is preventable going forward, even if the existing backlog is daunting.

Code debt often accumulates because the right solution wasn't known at the time, or because constraints forced shortcuts. Documentation debt usually accumulates because it wasn't prioritized—not because it was technically impossible. That means the cultural fix is more tractable than the technical one.

Teams that treat documentation as a first-class deliverable—not an afterthought, not a nice-to-have, not someone else's job—stop accumulating new debt at the same rate. The backlog is still there, but it stops growing. And a debt that isn't growing is a debt you can actually plan to pay off.

Your tech debt tracker is measuring half the problem. The other half is sitting in your docs, compounding quietly, and waiting for someone to put a number on it.

Time to build that dashboard.