Docs & Code Guide

Keep an internal wiki in sync: owners, archive policy, live visuals

Wikis fail by success: they make writing so easy that pages accumulate faster than anyone maintains them, until search returns three versions of the truth and readers stop trusting all of them. Keeping a wiki in sync is not a heroic rewrite; it is four standing mechanisms, ownership per page, a query that finds the dead weight, an explicit archive policy, and a gardening rotation, plus one trick that removes a whole class of staleness: visuals embedded by URL.

Try it free
7 min readFor teams whose Confluence search returns three contradictory answers

See it as a diagram

Everything below, as a diagram you can edit. Describe yours and see it in seconds.

193/2000• 3 credits left
Try:

No account needed · Editable canvas, not a picture

Ownership per page or nothing

A wiki page without an owner is a future lie: nobody is accountable when it drifts, and readers cannot tell whom to ask. The fix is metadata on every page that matters: an owner (a team, not a person, so it survives departures) and a review-by date. In Confluence this is a Page Properties macro plus a label; the same macro powers a Page Properties Report that renders a live table of every owned page and its review date, which turns "are our docs current" into a page you can open.

The rule that makes it stick: a page nobody will claim gets archived, not tolerated. Ownership is the price of staying findable.

Find the dead pages with a query

Staleness in a wiki is measurable. Confluence exposes CQL, a search language that filters by modification date, so the pages untouched in a year are one query away. On its higher tiers Confluence also has built-in analytics with per-page view counts, and the two together give a precise kill list: pages that are both old and unread are archive candidates; pages that are old but heavily read are the dangerous ones, stale content people still trust, and they go to the top of the review queue.

Pages untouched for a year, one space at a time (CQL):

  type = page AND space = "ENG" AND lastmodified < now("-52w")

Run it from Confluence search in CQL mode, or over the REST API:

  GET /wiki/rest/api/search?cql=type=page AND space="ENG"
      AND lastmodified < now("-52w")

Cross-reference with page analytics: old + unread = archive,
old + heavily read = review first, it is stale content people
still trust.

Archive beats delete beats ignore

Teams hesitate to delete because the page might matter, so they ignore instead, and ignored pages keep polluting search. The escape is an explicit archive policy. Confluence archiving keeps the page but drops it from default search results, which is precisely the property you want: history preserved, noise removed, restoration one click if anyone ever objects. Objections are rare; the fear of deleting is almost always fear of losing history, not of losing the page from search.

Write the policy down, three lines is enough: pages past their review date with no owner response are archived; archived pages are restored on request; deletion is reserved for content that is wrong and dangerous. A policy nobody has to argue about per-page is a policy that actually runs. The decay pattern this interrupts is described in wiki rot.

Gardening rotations

Wiki maintenance fails as a background duty and works as a named one. A gardening rotation gives one person per team a short, bounded shift, an hour or two per sprint: run the staleness query, ping owners past their review date, archive the unclaimed, merge the duplicates. Small and regular beats the annual cleanup that everyone dreads and no one finishes, and the rotation surfaces systemic problems, like a template that encourages copy-paste sprawl, that no individual editor sees. The heavier, scheduled version of this sweep is the documentation audit, with the service levels defined in a documentation SLA.

Visuals that update without page edits

One class of wiki staleness can be removed mechanically: the pasted diagram. A screenshot uploaded to a wiki page is frozen at upload; the same diagram embedded by URL is not. A Datadef project shared public serves an interactive embed page for iframe-capable wikis and a permanent image URL for everywhere else, and when the diagram is edited, every wiki page embedding it shows the new version within minutes, with zero page edits. One edit, or one update by an AI agent connected to the Datadef MCP server after an architecture merge, propagates to every page at once; nothing watches your repo, the update is one call away.

The honest limits: embeds require the project to be public, which may rule out sensitive architecture; Datadef handles the diagrams, not the prose around them; and a live diagram on a dead page is still a dead page, which is why this section is last and the ownership section is first. The platform mechanics are covered per tool in embed diagrams in Confluence.

The four standing mechanisms

Owner and review date on every page that matters, a staleness query run by a gardening rotation, an archive policy that runs without per-page debate, and diagrams embedded by URL so the visuals never join the rot.

FAQ

How do I keep an internal wiki up to date?

Four standing mechanisms. Give every page that matters an owning team and a review-by date in page metadata. Run a staleness query on a gardening rotation, in Confluence a CQL filter like lastmodified < now("-52w") finds pages untouched for a year. Enforce an archive policy so unclaimed stale pages leave search results instead of polluting them. And embed diagrams by URL so visuals update when their source changes, without page edits.

How do I find outdated pages in Confluence?

Query for them. CQL, available from Confluence search and the REST API, filters by modification date: type = page AND space = "ENG" AND lastmodified < now("-52w") lists pages untouched for a year. Confluence analytics, on its higher tiers, adds per-page view counts. Old and unread means archive candidate; old but heavily read means urgent review, because readers still trust it.

Should stale wiki pages be archived or deleted?

Archived, with rare exceptions. Archiving in Confluence keeps the page and its history but removes it from default search, which eliminates the noise without the fear of losing anything, and restoration is one click. Reserve deletion for content that is actively wrong and dangerous if found. An explicit three-line policy lets the gardening rotation act without per-page debate.

What is a wiki gardening rotation?

A named, bounded maintenance shift: one person per team spends an hour or two per sprint running the staleness query, pinging owners whose pages are past review, archiving unclaimed pages, and merging duplicates. It replaces the annual cleanup nobody finishes with small regular passes, and it surfaces systemic causes of sprawl that individual editors never see.

Can diagrams in a wiki update themselves?

The propagation can be automatic even though the editing is not. A diagram embedded by URL from a public Datadef project re-renders wherever it is embedded within minutes of an edit, so one change reaches every wiki page at once. The edit itself is made by a person or by an AI agent connected to the Datadef MCP server after a code change; Datadef does not watch repositories or edit diagrams on its own.