Docs & Code Guide

Cost of outdated documentation: a simple model over onboarding, incidents, and repeated questions

Outdated documentation costs engineering time on three measurable lines: extra ramp days for each new hire, extra minutes on each incident, and the steady drain of questions that a correct page would have answered. On typical mid-size team numbers the model lands around 400 engineer-hours a year, and the line that dominates is almost never the one teams guess: it is the repeated questions, because they compound weekly while onboarding and incidents are episodic.

Try it free
7 min readFor engineers building the case to fix the docs

See it as a diagram

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

136/2000• 3 credits left
Try:

No account needed · Editable canvas, not a picture

The model

Three lines, each a product of numbers you can count in your own systems: hires per year and ramp drag from onboarding surveys, incident count and duration from your incident tracker, question volume from a week of watching your team channels. The worked example below uses deliberately middle-of-the-road inputs; the point of the model is that you replace them.

Assumptions (replace with your own counts):
  new hires per year:           6
  extra ramp days per hire:     3     (stale setup guide, wrong architecture docs)
  incidents per year:           40
  extra minutes per incident:   20    (stale runbook, dead dashboard links)
  doc-shaped questions:         10/wk
  minutes per question:         15 asker + 15 answerer

Onboarding:  6 hires x 3 days x 8 h            = 144 eng-hours/yr
Incidents:   40 x 20 min                       =  13 eng-hours/yr (at the worst time)
Questions:   10/wk x 30 min x 48 wks           = 240 eng-hours/yr

Total: ~400 eng-hours a year, before counting any downtime cost.

The onboarding line

A new hire is documentation's heaviest user and least equipped victim: they cannot tell a stale page from a current one, so they follow the stale one to the end. Three extra days per hire is conservative for a team whose setup guide and architecture overview have drifted; ask your last two hires how long the docs cost them and use that number instead.

This line also carries a hidden multiplier: every wrong page a new hire follows teaches them to stop trusting the wiki and start interrupting people, which permanently inflates the questions line below. The mechanics of that knowledge concentration are the subject of tribal knowledge in engineering teams.

The incident line

Thirteen hours a year looks like the smallest line, and per hour it is the most expensive one: those 20-minute increments happen during outages, multiplied by customer impact and by every engineer waiting on the responder. A runbook pointing at a renamed dashboard or a decommissioned failover costs its minutes at the worst possible time, which is why stale runbooks are an incident risk in their own right, not just a docs annoyance.

If you track MTTR, you can firm this line up: tag incidents where responders reported doc trouble in the postmortem, and compare their durations against the rest.

The line that usually dominates

Repeated questions win because they never stop. Ten doc-shaped questions a week is modest for a team of eight, and each costs twice: the asker's search-then-ask cycle and the answerer's interruption, with the answerer usually being the same two senior people every time. At 30 combined minutes each, that is 240 hours a year, and the burden concentrates exactly on the engineers whose time is scarcest.

This line is also the easiest to measure this week: count questions in your team channel for five working days that an accurate page would have answered. Multiply by 48. Most teams find their count is above ten, not below.

About the numbers you will see quoted

Big circulating figures on the cost of bad documentation, hours per developer per week, billions per year, come overwhelmingly from vendor surveys with an interest in the answer, so this page does not lean on them. The time math above needs no authority: every input is countable inside your own team, and anyone who disputes the total can be handed the spreadsheet and invited to change the inputs. An argument from your own incident tracker beats an argument from any industry report.

The related question of how this cost accumulates structurally, as unpaid interest on skipped updates, is treated in documentation debt.

Cutting the other side of the ledger

The model prices the damage; the fix has a price too, and it is worth stating honestly. Verification passes cost minutes per page. Culling dead pages costs an afternoon. The expensive class of update, redrawing architecture diagrams, is the one where cost can structurally drop: a diagram an agent regenerates from the repository via the Datadef MCP server turns a 45-minute redraw into a command plus a review, invoked after a merge or in CI rather than by any automatic repo watching, with API access on paid plans. Cheaper updates mean the update happens, which moves all three cost lines at once.

Recovery for a surface already deep in staleness is its own playbook, covered in stale documentation.

Measure yours this week

Count doc-shaped questions in your team channel for five days, ask your last two hires what the docs cost them, and tag doc trouble in your next five postmortems. Those three numbers complete the model.

FAQ

What does outdated documentation actually cost?

Three measurable lines: onboarding drag (extra ramp days per new hire following stale guides), incident overhead (extra minutes per incident from stale runbooks, spent at the worst possible time), and repeated questions (each costing both the asker and the interrupted answerer). On moderate inputs, 6 hires losing 3 days each, 40 incidents losing 20 minutes each, 10 questions a week at 30 combined minutes, the total is roughly 400 engineer-hours a year.

Which cost of bad documentation is the biggest?

Usually repeated questions, not incidents or onboarding. Questions compound weekly all year, cost double (asker plus interrupted answerer), and concentrate on the most senior engineers. At 10 doc-shaped questions a week and 30 combined minutes each, that line alone is about 240 engineer-hours a year, dwarfing the episodic lines.

Is there research on the cost of poor documentation?

The widely quoted figures mostly come from vendor surveys with an interest in a large answer, so treat them as marketing rather than evidence. A stronger approach is local arithmetic: count your own doc-shaped questions for a week, ask recent hires what the docs cost them, and tag doc trouble in postmortems. Those inputs produce a number nobody in your org can dismiss.

How do I calculate the cost of outdated documentation for my team?

Multiply three products and add them: hires per year times extra ramp days times 8 hours; incidents per year times extra minutes attributable to doc trouble; doc-shaped questions per week times combined asker-plus-answerer minutes times 48 weeks. All three inputs are countable from onboarding feedback, your incident tracker, and a week of watching your team channel.

What reduces the cost of outdated documentation most?

Reducing the cost of updates, because updates that cost minutes actually happen. Verification passes instead of rewrites, culling pages nobody maintains, and generating what can be generated: architecture diagrams regenerated from the repository by an AI agent turn the most expensive manual update into a command plus a review. Every skipped update the model prices simply stops being skipped when it is cheap.