The documentation staleness problem: why PRs get merged but docs don't

Documentation goes stale for the same reason technical debt accumulates: there's a cost to fixing it and no immediate consequence for leaving it. The README that describes a deprecated setup process won't break anything. It'll just silently mislead the next person who reads it.

This is the documentation staleness problem, and it's structural — not a matter of team discipline or engineering culture.

How it happens

A new feature gets built and documented. Three months later, the feature gets refactored. The PR title is "Refactor: replace Redis queue with Postgres-backed job system." The code is correct. The tests pass. The PR gets merged.

The README still says "this service requires Redis." The architecture doc still has a diagram with a Redis box. The onboarding guide still has a step: "Install and start Redis."

Nobody lied. Nobody was careless. The documentation was just written for the state of the system at one point in time, and the system moved on.

Why "just update the docs" doesn't work

The standard advice is to treat documentation updates as part of the definition of done — no PR merges without the corresponding doc update. This sounds reasonable. In practice it fails for several reasons:

The update scope is unclear. When you're writing code, you know exactly what changed. When you switch to updating docs, you have to go find every place in the documentation that references the affected functionality. That's a different cognitive task, and it's easy to miss things.

Documentation review is not part of the review culture. PR reviewers check code correctness, test coverage, security implications. They're not usually reading the README to check whether it needs updating. Even if they were, they'd need to know what the README said before the change to notice that it's now wrong.

The connection between change and documentation is invisible. There's no automated signal that says "this PR touched the authentication module, and the authentication section of the README has not been updated in 4 months." Humans can't track this linkage across hundreds of PRs.

The real cost

Documentation debt has compounding costs that are easy to undercount:

Onboarding time. New engineers spend hours following instructions that lead them into dead ends. They either escalate to a senior engineer (who then has to context-switch) or they stumble through it alone. Either way, the cost of the stale doc is multiplied by every person who reads it.

Trust erosion. After following documentation that was wrong a few times, engineers stop trusting documentation. They go directly to reading code or asking colleagues. The documentation becomes invisible even when it's correct, because nobody reads it anymore.

Support load. For developer tools and APIs, stale documentation generates support requests. The answer to "why doesn't this work?" is usually "the docs are wrong, here's what actually works." That's a support ticket that didn't need to exist.

Solving it at the system level

The problem is structural, so the solution has to be structural. The core insight: the diff of a merged PR contains all the information needed to identify which documentation is now outdated. The code and the documentation describe the same system — when the code changes, you can reason about what the documentation should say.

This is what DocDr does. It reads each merged PR, compares the diff against your documentation files, and generates a draft PR with proposed updates. A human reviews the draft before anything merges — the automation handles discovery and drafting, the developer handles approval.

The result is that documentation debt stops accumulating. Every merge that changes documented behavior triggers a documentation review. The docs don't stay current because someone remembered to update them; they stay current because the process keeps them current.

When docs are already badly stale

If your documentation is already significantly out of date, fix it before enabling per-merge automation. Trying to do incremental updates on a README that's two years out of date will produce confusing results.

DocDr has a bootstrap mode for this: it takes your current repo structure, entry points, and package manifests and generates fresh documentation from scratch. Use bootstrap to get to a correct baseline, then enable maintenance mode for ongoing updates.

The goal isn't perfect documentation — it's documentation that's accurate enough to be trustworthy. Once developers trust the docs again, they read them. Once they read them, the investment in keeping them current pays off.