# Documentation rots quietly

*28 Aug 2026* · Stella Ellervee

Stale docs don't announce themselves. The only fix that has worked is making rot measurable instead of relying on people to notice.

_Placeholder — written by Claude, not by Stella_

---

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.