Why documentation goes stale, and what to do instead
Documentation is written once and silently drifts. Records that know when they are out of date work differently.
Every company has tried to fix lost knowledge with documentation. Most companies have a wiki full of pages that were true once.
Three reasons it fails
It is written at the wrong moment. Docs get written at launch, when people are busiest, or at handover, when they are leaving. Both are the worst moments to explain decisions carefully.
It asks for too much. “Document the refund system” is a day of work. Nobody has a day. The result is either nothing, or a page that describes the obvious and skips the reasons.
Nothing tells you when it is wrong. The code changes in a pull request. The page doesn’t. Nothing connects the two, so a reader cannot tell a current page from a three-year-old one.
What works better
- Small, specific questions instead of documents. “Why 30 days rather than 60?” takes a minute to answer and records the part that matters.
- Asked at the right moment. While the person still remembers, not on their last day.
- Tied to the system. The answer is attached to the rule it explains, so a change to the rule flags the answer.
- With a status. A reader sees whether an answer is Approved, Stale or Unknown before relying on it.
The test
For any page in your wiki, ask: if the system changed tomorrow, would anyone know this page was wrong? If the answer is no, the page is already decaying. See Keeping answers current.
The 15% cap nobody could explain
42% of what your company knows lives in one person's head