Nobody wrote docs because nobody read them

The documentation chicken-and-egg problem is one of the most persistent failure modes in software organizations. Nobody reads the docs because the docs are outdated and unreliable. Nobody writes the docs because nobody reads them and the effort feels wasted. Both sides of the cycle are individually rational and collectively catastrophic. The result is an organization where the official documentation exists as a facade — it's there, it covers the right topics, but it doesn't reflect reality and nobody trusts it.

This isn't a motivation problem or a culture problem in the usual sense. It's an incentive structure problem. The person who writes documentation pays a real cost (time, effort) and receives almost no benefit — the documentation goes unread, the writer receives no recognition, and the time could have been spent on features that are visibly valued. The person who reads documentation pays a lower cost (a few minutes of search) but receives an uncertain benefit — maybe the doc is accurate, maybe it's two years out of date and will send them in the wrong direction. Rational actors on both sides skip documentation entirely and go straight to asking a colleague.

The consequence for AI agents is severe. An agent that reads your documentation and acts on it will produce results calibrated to whenever the docs were last updated. In a typical L1 organization, that might be 18 months ago. The agent isn't wrong — it followed the documented procedure. The procedure is wrong. This is worse than having no docs at all: it creates confident, plausible-looking failures that are hard to diagnose.

At L1, organizations typically have documentation systems (a wiki, a Confluence space, a docs/ folder in the repo) but the content inside them has rotted. The system exists because someone thought it was a good idea years ago. The content was never maintained because the incentive structure never changed. The cycle continues until something external breaks it.

• Confident wrong answers are worse than no answers - stale documentation gives agents and new hires a false sense of having the right procedure, leading to failures that are harder to diagnose than "I don't know how to do this"
• The cycle is self-reinforcing - every time someone consults the docs and finds them wrong, they trust them slightly less and are slightly less likely to write documentation themselves, accelerating the decay
• Agents amplify the problem - a human who finds stale docs asks a colleague; an agent that finds stale docs executes the stale procedure at machine speed and scale
• Search engines and LLMs learn from your docs - if your internal docs are indexed, stale procedures will be surfaced confidently by AI assistants who don't know the docs are wrong
• The fix is organizational, not individual - no amount of individual motivation overcomes a broken incentive structure; the cycle breaks only when reading and writing docs both become reliably valuable

1. Audit documentation accuracy before investing in coverage - pick 10 random docs and verify whether they are accurate today. If fewer than 7 of 10 are accurate, coverage is not your problem — accuracy is. Fix accuracy before adding more content.
2. Add a "last verified" date to every doc - make staleness visible. A doc with a "last verified: 2022-03-15" header signals its own unreliability. This creates demand-side pressure: engineers stop trusting old docs, which creates supply-side pressure to keep docs current.
3. Require docs updates as part of every PR that changes behavior - add "docs updated?" to your PR template. Make it a non-optional checklist item, not a good-faith question. Code that changes behavior without updating the corresponding documentation fails review.
4. Create a "docs owner" rotation, not a permanent owner - permanent owners create single points of failure and rarely maintain docs. Rotating ownership (one engineer owns the docs for one area for one quarter) distributes the maintenance cost and ensures more engineers have a stake in documentation quality.
5. Measure documentation accuracy, not coverage - count the percentage of docs that are accurate today, not the number of docs that exist. Coverage metrics reward writing docs nobody reads; accuracy metrics reward maintaining docs that actually help.
6. Make docs easy to find before making them comprehensive - the most common reason docs go unread is not their quality but their discoverability. Ensure every repository has a README that links to relevant docs, and every runbook is linked from the system it describes.

Starting with a documentation sprint that doesn't change the process. A sprint that creates 50 new docs without changing the PR process, ownership model, or accuracy metrics will decay in 6 months. The sprint is wasted unless the underlying incentive structure changes alongside the content.

Using a wiki as the primary home for procedural docs. Wikis decouple documentation from code, making it easy for docs to drift. Runbooks and procedural docs belong in the repository they describe, where they're visible in PRs, can be linted, and are co-located with the code that would invalidate them.

Confusing documentation quantity with documentation quality. Organizations that measure lines of documentation or number of pages reward bloat. A 200-page architecture guide that nobody reads is worse than a 10-page guide that every engineer has memorized. Prefer concise, accurate, and frequently consulted over comprehensive, stale, and ignored.

Expecting voluntary compliance. "Please update the docs when you change behavior" is an ineffective norm without enforcement. Documentation updates need to be structurally required — in PR templates, in definition of done, in CI checks that verify docs exist for certain file types. Voluntary compliance produces 30% participation at best.

Not rewarding documentation work in performance reviews. If engineers are evaluated on features shipped and bugs closed, documentation work is invisible overhead. Engineering managers need to explicitly recognize documentation contributions in review cycles — not just for culture reasons, but because people respond to what is measured and rewarded.