Documentation Debt: Counting Stale Pages Across a 60-Person Company

Of 780 internal documents, 214 had not been edited in over a year and 61 described a process that no longer existed. The count took two people nine hours and produced an uncomfortable ratio: roughly one document in four was stale.

The company built software for insurers and had grown from 30 to 60 people in eighteen months. Documentation had grown with it, without a review habit.

How staleness was defined

Two tests were applied. A mechanical test, which was no edit in twelve months. A judgement test, which was whether the document still matched what a person actually does, checked by asking the owner a single question: would you follow this today.

Two hundred and fourteen failed the mechanical test. Sixty-one failed the judgement test, and 34 of those had been edited within the year, which is the more interesting group.

The documents that were recently edited and still wrong

Editing a document is not the same as verifying it. A page can be updated with a new link, a new name or a corrected typo and remain wrong about the process it describes.

The 34 documents in this group all had small recent edits from someone passing through, which reset the clock without resetting the content.

The cost of one stale page

Three specific incidents were traced. A stale runbook caused a 40-minute outage because a restart step referred to a service that had been split. A stale onboarding page sent two new hires to a tool that had been replaced. A stale policy page produced eight support tickets asking the same question.

None of these were catastrophic. Together they accounted for about eleven hours of avoidable work in a quarter, which is roughly what the audit cost to run.

The review scheme

The company adopted a three-part scheme: every document has a named owner, a review date no more than six months out, and a status line at the top saying current or superseded. Owners confirm or change; nobody is asked to improve.

Documents failing the review date are flagged in the index but not deleted, because deleting a stale document removes the history of why the process changed.

What happened in the first cycle

Owners confirmed 480 documents and changed 94. Fifty-one were marked superseded and linked to a replacement. Nine were deleted after their owners agreed nothing referenced them.

The first cycle took about four minutes per document, spread across 60 people, which is roughly six hours of company time per month. That number was the main objection and it did not go away.

The honest counter-argument

Six hours a month is not trivial. The counter-argument is that the eleven hours of avoidable work in a quarter came from three documents, and nobody could predict which three, so the review has to cover everything or nothing.

The company accepted that reasoning and reduced the scope instead: only documents referenced from the onboarding schedule, the runbooks and the support macros are in the mandatory cycle. That is 240 documents rather than 780.

Two cycles on

Documents failing the mechanical test fell from 214 to 68. Judgement failures fell from 61 to 12, and the recently-edited-but-wrong category fell from 34 to 6, mostly because the status line forces a decision rather than a passing edit.

Who does the reviewing

Owners confirm their own documents, which is cheap and slightly circular. A page about a process is confirmed by the person who runs it, so a process that is broken and consistently practised will pass every cycle.

The company accepted the circularity and added one external check: each team reviews one document belonging to another team, chosen at random. That catches about a third of the judgement failures the self-review misses.

The index nobody wanted to build

The index was built as a single table by one person in a day, and it is the only artefact that makes the scheme auditable. Without it, a review date is a line at the top of a page that no one aggregates.

It is also the part most likely to be abandoned, because it produces no visible benefit until someone asks how many pages are stale.

One document in four was stale when the count started. It is now one in eleven, across a narrower set, and the index shows its own review date so the count can be repeated without an audit.