How much is bad documentation actually costing you?

Bad documentation is one of those costs that hides in plain sight. Nobody has a budget line for "time wasted because things aren't written down." Nobody tracks "decisions relitigated because nobody documented the original discussion." Nobody measures "bugs caused by engineers who didn't understand why the system was built this way." But all of these are real costs, and when you add them up for even a modest engineering team, the total is large enough to be worth addressing.

Here's how to calculate your number.

Category 1: Senior engineer interruptions

Every question a colleague answers verbally is time that could have been spent on engineering work. The cost is the interruption itself plus the recovery time: roughly 25 minutes of lost focus per interruption.

Your inputs:

• Number of senior engineers

• Estimated interruptions per day for documentation-answerable questions (typically 3-8)

• Average recovery cost per interruption: 25 minutes

• Senior engineer loaded hourly rate

Example: 5 senior engineers × 5 interruptions/day × 25 minutes × $95/hour × 250 working days = $248,000/year

Most teams underestimate the interruption count because each individual interruption feels trivial. Track it for a week and the number is usually higher than expected.

Category 2: Onboarding delays

Every week a new hire spends ramping that could have been shortened by better docs is a week of salary paid for reduced output.

Your inputs:

• Number of engineering hires per year

• Estimated weeks of ramp time with current documentation

• Estimated weeks of ramp time with good documentation (typically 40-60% shorter)

• New hire monthly loaded cost

Example: 8 hires/year × 4 weeks of avoidable ramp time × $4,500/week loaded cost = $144,000/year

Category 3: Relitigated decisions

When past decisions aren't documented, teams spend meeting time debating questions that have already been resolved. The cost is the meeting time multiplied by the number of attendees.

Your inputs:

• Estimated hours per month spent in meetings relitigating past decisions

• Average number of attendees in those meetings

• Average loaded hourly rate

Example: 4 hours/month × 5 attendees × $85/hour × 12 months = $20,400/year

This looks small, but the indirect cost is larger: relitigated decisions delay the work that depends on them, and the delay cascades through the sprint.

Category 4: Knowledge loss from departures

When a key engineer leaves and their knowledge isn't documented, the team absorbs a productivity hit while reconstructing the context that departed with them.

Your inputs:

• Number of key departures per year

• Estimated weeks of reduced team productivity per departure

• Team cost per week during reduced productivity

Example: 2 departures/year × 6 weeks of reduced velocity × $15,000/week team cost × 30% productivity reduction = $54,000/year

Category 5: Errors from missing context

Bugs and mistakes caused by engineers who didn't understand why a system was built the way it was. These are the hardest to quantify but often the most expensive, because a conceptual misunderstanding can produce bugs that are difficult to diagnose and costly to fix.

Your inputs:

• Estimated incidents per year attributable to missing documentation or context

• Average cost per incident (engineering time to diagnose, fix, and review)

Example: 6 incidents/year × $5,000 average cost = $30,000/year

Category 6: AI tools operating without context

Your AI coding tools, internal agents, and automation perform at a fraction of their potential because the engineering context they need isn't documented and searchable. This is the hardest category to quantify because it's an opportunity cost rather than a direct cost: the value your AI tools could provide if they had proper context versus the value they provide without it.

Estimated impact: If your AI tools are 30-50% more effective with comprehensive documentation, and your team spends 2-3 hours per day interacting with AI tools, the recovered productivity from better-documented context is meaningful even at conservative estimates.

Adding it up

For a 20-person engineering team with moderate hiring and typical documentation quality:

This is before counting the AI opportunity cost. For a 20-person team, the total documented cost of bad documentation is roughly half a million dollars per year, which is the equivalent of two to three engineering headcount spent on problems that comprehensive documentation would largely eliminate.

The comparison

Self-writing documentation that generates and maintains itself from your team's GitHub activity, Slack conversations, and meetings costs a fraction of one engineering salary. If it addresses even 50% of the costs above, the return on investment is ten to twenty times the cost of the tool.

The question for most engineering leaders isn't whether bad documentation is expensive. It's that nobody has added up the costs before, because each category is distributed across dozens of small inefficiencies that individually feel insignificant.

They're not insignificant. They're just invisible until someone calculates them.

Frequently asked questions

Are these numbers realistic for smaller teams? Scale them proportionally. A ten-person team with fewer hires and fewer interruptions will have a lower total, but the per-engineer cost is similar. Most teams of ten or more are losing $100K+ per year to documentation problems. The cost grows non-linearly with team size because the tribal knowledge bottleneck gets worse as the team grows.

What if we already have some documentation? Adjust the estimates for the areas where your docs are strong. If your onboarding docs are good but your decision documentation is missing, the onboarding cost will be lower but the relitigation cost will be higher. Most teams have pockets of good documentation surrounded by significant gaps.

How do we convince leadership to invest in documentation? Calculate your specific number using the categories above with your team's actual data. Present it alongside the cost of the solution. The ROI calculation is usually compelling enough on its own, because the cost of the problem is large and the cost of the solution is comparatively small.

Related reading: The cost of writing engineering docs, The real cost of engineering onboarding, The bus factor, Good docs are a 10x multiplier. Related pages: Self-writing docs, For engineering teams, Knowledge retention.