Documentation Decay Half-Life
Organizations invest in documentation to ensure knowledge transfer, reduce bus factor, and onboard new team members faster. The initial documentation push produces comprehensive wikis, runbooks, and architecture decision records. But documentation has a half-life. Code changes but docs don't. APIs evolve but their docs stay frozen. Within 6 months, 30-40% of technical documentation is outdated. Within a year, it's over 50%. The problem compounds: once developers encounter outdated docs a few times, they stop trusting all documentation. They go straight to the code or ask a colleague. The documentation investment becomes a liability — worse than no docs, because outdated docs actively mislead. The team that was supposed to benefit from documentation now spends time debugging issues caused by following stale instructions.
What people believe
“Documentation ensures knowledge transfer and reduces onboarding time.”
| Metric | Before | After | Delta |
|---|---|---|---|
| Documentation accuracy at 12 months | 100% (at creation) | ~50% | -50% |
| Developer trust in docs | High (initial) | Low (after stale encounters) | -70% |
| Onboarding time with stale docs | Reduced (good docs) | Increased (misleading docs) | Worse than no docs |
| Incident resolution with stale runbooks | Faster (accurate runbook) | Slower (wrong procedures) | +30% MTTR |
Don't If
- •You're planning a one-time documentation push without a maintenance plan
- •Your team doesn't have a process for doc review tied to code changes
If You Must
- 1.Tie documentation updates to code review — no PR merges without doc updates
- 2.Add expiration dates to all docs and automate staleness alerts
- 3.Keep docs close to code (README in repo, not separate wiki)
- 4.Document decisions and context, not just procedures — decisions age better
Alternatives
- Architecture Decision Records (ADRs) — Document why decisions were made — these don't go stale
- Living documentation from tests — Tests as documentation — always current because they run in CI
- Code-adjacent docs — Docs in the same repo as code, reviewed in the same PR
This analysis is wrong if:
- Organizations with comprehensive documentation maintain accuracy above 80% at 12 months without dedicated maintenance effort
- Developers consistently trust and use documentation even after encountering outdated content
- One-time documentation investments produce lasting onboarding improvements beyond 6 months
- 1.Stripe Developer Documentation Study
Internal study showing documentation accuracy drops below 60% within 12 months without active maintenance
- 2.Google Engineering Practices: Documentation
Google's approach to keeping documentation current through code review integration
- 3.Thoughtworks Technology Radar: Documentation as Code
Recommendation to treat documentation with the same rigor as code — version controlled, reviewed, tested
- 4.Atlassian: The Cost of Outdated Documentation
Survey showing developers spend 30 minutes per day dealing with outdated or missing documentation
This is a mirror — it shows what's already true.
Want to surface the hidden consequences of your organizational design?