Wiki rot: the mechanics of how wikis decay, the orphaned-page metric, and the archive policy that stops the spiral

The loop starts innocently: a page goes stale because the system it describes changed. Search does not know that, so the stale page keeps ranking, often above newer content, because age accumulates the links and views that ranking rewards. A reader follows it, gets burned, and updates their behavior, not the page: next time they ask a colleague instead, or skim past search results toward whatever looks newest.

Writers complete the loop. Editing an existing page means first verifying which of its claims still hold, which is slower and riskier than writing fresh, so the rational move under deadline is a new page titled Payments architecture (current). Now two pages compete in search, future edits split between them or land on neither, and both rot. Every turn of the loop makes search worse, trust lower, and duplication more rational. That is why rot accelerates: the wiki is not decaying linearly, it is compounding.

The orphaned-page count is the structural metric: pages with no incoming links from any other page. Orphans are invisible to link-following readers and reachable only through search, which is exactly where they do damage, dead content that only ever surfaces in the worst context. Confluence can list pages with no incoming links under a space's page-management tools, and on any platform the ratio of orphans to total pages tracks rot better than raw page age does.

The dead-search rate is the behavioral metric: searches that end with no click, or with a click followed by an immediate return to search. Rising dead-search rate means readers are querying, finding, and rejecting, the middle of the rot loop, observable before the duplication wave starts. Confluence surfaces search behavior in its admin analytics on plans that include analytics; failing that, a periodic survey question, did you find what you searched for this week, is a cruder gauge of the same thing.

Confluence gives rot diagnosis real instrumentation. CQL, its query language, can pull every page untouched past a threshold, ordered oldest first, which is the raw material for the audit sheet. Per-page view counts come from the analytics REST API on plans that include analytics, letting you separate the genuinely dead, old and unread, from the load-bearing fossils, old and heavily read, which are your urgent fixes rather than archive candidates.

The Confluence graveyard has a recognizable shape: spaces belonging to teams that no longer exist, still indexed, still ranking for queries the current org makes. Space-level last-activity dates find them fast, and whole-space archival is usually the right verdict.

# Every page in the ENG space untouched for a year, oldest first
curl -s -u [email protected]:$CONFLUENCE_API_TOKEN \
  --get "https://your-site.atlassian.net/wiki/rest/api/content/search" \
  --data-urlencode 'cql=space = ENG and type = page and lastmodified < now("-52w") order by lastmodified asc' \
  --data-urlencode 'limit=100'

The structural intervention is making removal cheap, because rot persists when deletion feels dangerous. An archive-first policy sets the default action for a failing page to archive rather than delete: in Confluence, archived pages drop out of default search results while remaining restorable, which directly repairs the loop's first step, search stops surfacing the dead. Nothing is lost, so the objection that stalls every cleanup, someone might need it, loses its force.

The policy that works is mechanical: any page meeting two of, no owner, near-zero views over 90 days, failed an accuracy check, superseded by a newer page, gets archived in a monthly batch, announced with a one-week objection window. The companion habit is a redirect note: when a new page supersedes an old one, the old page is archived and the new one is linked from wherever the old one was linked, so the duplication fork the rot loop depends on never establishes. Running this end to end is the documentation audit checklist; the ongoing process that prevents recurrence is keeping an internal wiki in sync.

On any wiki old enough to rot, the architecture diagrams are the most-rotted artifacts, because a pasted diagram export is frozen at paste time while the prose around it can at least be patched in seconds. A reader can forgive an outdated sentence; a confidently wrong picture of the system is what converts them to the ask-a-colleague workflow permanently.

The structural fix mirrors the archive policy: stop storing frozen copies. A Datadef diagram embedded in the wiki by URL follows its source, an edit shows up in every embedding page within minutes, so the wiki page can no longer hold a private stale copy. Honesty about the remaining work: the embed requires the project to be shared public, someone or some agent still has to update the diagram when the architecture changes, Datadef does not watch your systems, and prose rot is untouched by any of this. What the embed removes is the multiplication, one stale export per page, which is the same multiplication the rot loop feeds on. The general diagnosis beyond wikis is covered in stale documentation, and the README-specific variant in readme rot.

• Stale documentation
• Keep an internal wiki in sync
• README rot
• Documentation audit checklist