Documentation review cadence: verify and stamp, at a rhythm set by the doc type

The reason review schedules die is that teams define review as improve, and improving a page takes an hour nobody has. Define it as verify instead: confirm the commands still run, the service names still exist, the diagram still matches production, the links still resolve. Fix anything fixable in under five minutes inline. Anything bigger becomes a ticket, and if the page is mostly wrong, the honest outcomes are a rewrite ticket or archival, not a polite pass.

Then stamp it: a last-verified date and the verifier's name, distinct from last-edited. The stamp is the entire output of a passing review, and it is the datum every freshness dashboard and documentation SLA runs on. A review that ends without a stamp update did not happen, as far as the tooling can tell.

One cadence for all docs fails in both directions: runbooks rot in a quarter while ADRs never need review at all. Set the cadence per class and write it down; the table below is a defensible starting point that a docs freshness policy can adopt wholesale.

Generated documents earn the lightest treatment: an API reference built from source in CI needs no calendar review, only a regeneration hook on release. Generated architecture diagrams shift the review from redraw to glance-and-confirm, which is most of why cheap regeneration changes the cadence math, as covered in how often architecture diagrams should be updated.

Doc type            Calendar floor   Event trigger
Runbooks            30 days          after every incident that used one
Service overviews   90 days          major change merged to the service
Architecture pages  90 days          service added/removed, dependency
                                     changed, datastore swapped
Onboarding guides   180 days         each new-hire cohort finishes
ADRs                none             immutable: supersede, never edit
Generated refs      none             regenerate on release

Events should trigger most reviews, because events know which page went stale: the incident that used a runbook is the best possible reviewer of that runbook, and the merge that split a service is the moment its overview needs eyes. The calendar exists as a floor underneath the triggers, catching the pages whose events nobody fired. A page reviewed only by calendar is a page whose triggers are miswired, which is worth noticing in itself.

The floor also bounds the damage of a silent failure: with a 90-day floor, the worst case for a missed trigger is one quarter of drift rather than three years of it.

The document owner reviews, because verification requires knowing what true looks like. Two placements make it stick without a standing meeting: on-call reviews every runbook they actually opened during their rotation, stamping as they go, and each engineer picks one page from the stale queue per sprint, a task sized in minutes that survives sprint pressure precisely because it is small.

A team of six with 40 owned pages on the table above averages roughly 15 reviews a month, or two to three short checks per person. That is the entire cost of a wiki that stays credible, and the annual all-hands docs cleanup week disappears in exchange.

• Documentation SLAs
• A docs freshness policy template
• How often should architecture diagrams be updated
• Documentation audit checklist