Documentation rots quietly

Nobody files a ticket saying “this page is out of date.” Stale documentation fails silently: someone reads it, acts on it, gets a slightly wrong result, and concludes the docs are unreliable in general. After that they stop reading, and the page’s wrongness never gets reported because nobody is looking at it.

The interesting question is not “how do we write better docs” but “how do we find out a page has gone stale without a human noticing.”

Two things that helped:

• A staleness checker. Last-modified date, owner, and whether the page still matches the thing it describes. Pages with no owner are the worst offenders, because there is nobody for the check to nag.
• Read counts, split by human and machine. Confluence audit logs can distinguish a person opening a page from a CLI fetching it. That difference turns out to matter: a page with high machine reads and no human reads is load-bearing for agents and invisible to everyone else.

The second one changed how I think about the first. Effort spent on a page that nothing reads is waste, and until you can see reads you are guessing.