The Documentation Half-Life Problem

Subject: Your docs are wrong within 3 months

Hey there,

A new engineer joined one of my client's teams and followed the onboarding documentation. Three days in, they'd set up a local environment that hadn't worked since August, configured a deprecated authentication flow, and connected to a staging database that was decommissioned 4 months ago.

The documentation was beautifully written. It was also 40% wrong.

●This Week's Decision

The Situation: Your team invested in documentation. Architecture decision records, onboarding guides, API docs, runbooks. Six months later, half of it is outdated. Engineers stopped trusting the docs and started asking Slack instead. The documentation investment feels wasted.

The Insight: Documentation has a half-life ... the time it takes for 50% of the content to become inaccurate. I've measured this across 5 teams:

Documentation Half-Life by Type:
────────────────────────────────
Process docs (how to deploy, run tests):    1 month
Onboarding guides:                          2 months
Architecture overviews:                     3 months
API reference (auto-generated):             Indefinite
ADRs (Architecture Decision Records):      Indefinite

The pattern: docs that describe "how" decay fast.
Docs that describe "why" stay accurate.

The solution isn't writing better docs. It's accepting that some documentation is disposable and building systems to catch decay.

Three strategies that work:

1. Generate what you can. API docs from OpenAPI specs, database schemas from migrations, dependency graphs from code. Generated docs are always current because they're derived from the source of truth.

2. Test what you can't generate. Onboarding docs are the highest-decay, highest-impact category. The test: every new hire follows the onboarding guide exactly as written. Any step that fails gets fixed immediately. One team I advise makes it the new hire's first PR ... fixing the onboarding doc.

3. Budget for maintenance. Documentation maintenance isn't a one-time project. Allocate 5% of sprint capacity to documentation upkeep, distributed across the team. Not a "documentation sprint" once a quarter ... 2 hours per engineer per sprint reviewing and updating the docs they own.

The concept I use: assign documentation owners. Every document has a name next to it. That person is responsible for reviewing it monthly and either confirming it's current or updating it. When the owner leaves the team, ownership transfers explicitly in their offboarding checklist.

The anti-pattern: a wiki with 400 pages and no owners. That's not documentation ... it's an archaeological site. Better to have 40 accurate, owned pages than 400 pages where engineers have to guess which ones are still valid.

When to Apply This:

• Teams where onboarding takes more than 2 weeks and new hires report "the docs were wrong"
• Organizations with more than 100 pages of documentation and no review process
• Engineering leaders spending more than 5 hours/week answering questions that documentation should cover

●Worth Your Time

1. Stripe: Documentation-Driven Development ... Stripe built Markdoc to keep their docs in sync with their codebase. The key insight: documentation lives alongside code, reviewed in the same PRs, tested in the same CI pipeline. When documentation is a code artifact, it decays at the same rate as code ... which is manageable.

2. Divio Documentation System ... The clearest framework for documentation types: tutorials, how-to guides, reference, and explanation. Each type has a different half-life and maintenance strategy. Mixing them (the most common mistake) makes everything harder to maintain.

3. Google: Documentation Best Practices ... Google's internal documentation standards emphasize freshness over completeness. Their rule: delete documentation that's more than 6 months stale without an owner. Controversial, but better than misleading engineers with outdated content.

●Tool of the Week

Mintlify ... Documentation platform that detects stale content automatically. It flags pages that haven't been updated since the codebase changed, surfaces broken links, and generates update reminders for document owners. If your documentation problem is "we don't know what's outdated," Mintlify solves the detection half of the problem. You still need humans to fix it.

That's it for this week.

Hit reply if you want help designing a documentation maintenance system for your team ... the setup takes one sprint and saves hours per week. I read every response.

– Alex

P.S. For the leadership framework on building sustainable engineering processes: Engineering Leadership: Founder to CTO.