Why documentation goes stale, and the review cycle that fixes it
Ask any team why their documentation is out of date and you will hear the same answer: everyone meant to update it. The intent is never the problem. The problem is that updating a page is the one task with no deadline attached to it, competing against work that has one.
Staleness is a scheduling failure, not a discipline failure
Teams tend to treat out-of-date documentation as a cultural weakness, which leads to campaigns, reminders and eventually resignation. It is more useful to treat it as a scheduling failure. A page that nobody is responsible for, with no date attached, will lose every prioritisation conversation it enters.
The fix is unglamorous. Give the page an owner, give it a review interval, and make the passing of that interval visible to somebody who can act on it. The work does not become more interesting, but it does become schedulable.
Set a review interval that matches the rate of change
A quarterly review for everything is a policy nobody keeps. Set the interval by how fast the underlying subject moves. Deployment runbooks and API references change with the code and deserve a short cycle. A company policy or an architectural principle can hold for a year without embarrassment.
Where the page describes something with its own release rhythm, tie the review to that rhythm instead of the calendar. A runbook for a service can be flagged when that service ships a change, which is far more accurate than a date chosen when the page was written.
Make the review small enough to actually do
A review that means rereading four thousand words will be postponed. A review that means confirming three specific claims will be done in the meeting it was raised in. Break long reference documents into pages with a single subject each, so the unit of review is small.
It also helps to record what the reviewer checked. A note saying the commands were run against staging on the eighteenth is worth more to the next reader than a green tick, and it turns the review into evidence rather than a formality.
Report on the gap, not on the volume
The usual documentation metric is page count, which measures effort rather than usefulness. Track instead the proportion of pages past their review date, the number of pages without an owner, and the searches that returned nothing anyone opened.
Those three numbers tell you where the documentation is failing its readers. They also make a short and honest agenda item, which is generally what turns a good intention into recurring work.
Written by the DocuRail Team.
Get the next one
One piece a month on documentation practice.