Docs & Code Guide

Documentation audit checklist: inventory, owners, spot checks, and the delete pass in one afternoon

A documentation audit does not need a quarter or a committee. For a space up to a couple hundred pages, two people and four focused hours produce a complete inventory, an owner per page that deserves one, a measured accuracy rate, and a shorter wiki. The checklist below is ordered so each step feeds the next, with the spreadsheet columns and time budget included.

Try it free
7 min readFor the person who volunteered to clean up the wiki

See it as a diagram

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

177/2000• 3 credits left
Try:

No account needed · Editable canvas, not a picture

The one-afternoon shape

Budget four hours for up to roughly 200 pages: 60 minutes for the inventory, 45 for ownership, 90 for spot checks, and 45 for the archive pass. Two people beat one, not for speed but because the spot-check protocol works best when the checker is not the author. Past 200 pages, audit one space or one team's section at a time rather than stretching the afternoon; a finished partial audit beats an abandoned full one.

Set the goal before starting: the output is a spreadsheet with a verdict per page, not a rewritten wiki. Rewriting happens afterwards, by the owners the audit assigns.

Step 1: build the inventory (60 minutes)

Export every page with its last-edited date. In Confluence, a CQL search over the space ordered by lastmodified gets you the list; in Notion, a script over the wiki database reading last_edited_time; for repo docs, git ls-files with a date loop. Paste it all into one sheet, one row per page, whatever the source system.

The columns that make the rest of the audit mechanical: page URL, title, owner, last edited, last verified, views over 90 days if your platform exposes them, spot-check result, verdict, and notes. Verdict gets exactly four allowed values: keep, update, archive, delete.

page_url,title,owner,last_edited,last_verified,views_90d,spot_check,verdict,notes
wiki/eng/payments-architecture,Payments architecture,@mina,2025-11-04,2025-03-10,412,fail,update,diagram missing the fraud-scoring service
wiki/eng/deploy-runbook,Deploy runbook,@sre-team,2026-06-21,2026-06-21,988,pass,keep,
wiki/eng/kafka-setup-2022,Kafka setup (2022),,2022-09-14,,3,not-run,archive,superseded by streaming-platform page
wiki/eng/onboarding,Engineering onboarding,@platform-team,2026-01-15,,655,fail,update,3 of 14 links broken

Step 2: an owner per page, or a verdict instead (45 minutes)

Go down the sheet assigning an owner to every page worth keeping, a team alias rather than an individual wherever possible. The pages nobody claims are the interesting ones: a page that describes a live system but has no natural owner goes to the team running that system, and a page no team recognizes is an archive candidate by default, regardless of its content. Which ownership shape fits your org, and what happens when owners leave, is its own decision, compared in documentation ownership models.

Step 3: the spot-check protocol (90 minutes)

Pick ten pages readers actually use, the top of the views column, not a random sample, and follow each one literally. Run the commands a runbook gives, click every link, open the consoles a setup guide names, and hold each architecture diagram against what the infrastructure actually contains, using the checks from how to detect stale diagrams. Record pass or fail per page, where fail means a reader following this page would be misled or blocked.

The failure rate over ten high-traffic pages is your accuracy estimate for the space, and it is usually the number that gets leadership to fund the fixes. Four fails out of ten on your most-read pages is a concrete statement in a way that the wiki feels outdated never is.

Step 4: the archive pass (45 minutes)

Archive, not delete, as the default: archiving keeps the page restorable while removing it from readers' paths, which removes the fear that stalls cleanup. A page earns the archive verdict on any two of: no owner claimed it, single-digit views over 90 days, failed its spot check, or duplicates a newer page. Reserve delete for the unambiguous cases, drafts, duplicates, event pages from years past.

Announce the archive list in the team channel with a one-week objection window, then execute all at once. The mechanics of why unread pages actively damage the wiki they sit in, and the metrics behind the archive-first policy, are the subject of wiki rot.

The whole checklist

Inventory every page with dates into the sheet. Assign an owner or an archive verdict to each. Spot-check the ten most-read pages by following them literally. Archive what failed and what nobody claimed, with a one-week notice. Book the next audit before closing the sheet.

Cadence, and shrinking the next audit

A full audit yearly and a light pass quarterly, inventory refresh plus spot checks only, keeps the sheet honest without becoming a ritual. The recurring cost center in most audits is diagrams: they fail spot checks more often than prose because they age silently. That cost shrinks when published copies stop being frozen exports. A Datadef diagram embedded by URL follows its source, so fixing the diagram once fixes every page that embeds it within minutes; the embed requires the project to be shared public, which rules it out for confidential architectures. Updating the diagram itself stays a deliberate act, by a person or an agent, so the audit's diagram spot check never fully disappears. It just stops multiplying by the number of pages.

FAQ

What should a documentation audit checklist include?

Four steps: a full inventory of pages with last-edited dates, an owner assigned to every page worth keeping, an accuracy spot check where you follow the ten most-read pages literally and record pass or fail, and an archive pass for pages that failed, are unclaimed, or are unread. The output is a spreadsheet with a verdict per page: keep, update, archive, or delete.

How long does a documentation audit take?

About four focused hours for a space up to roughly 200 pages, split as 60 minutes inventory, 45 minutes ownership, 90 minutes spot checks, and 45 minutes for the archive pass. Larger wikis are better audited one space at a time than in one long effort.

How many pages should I spot-check in an audit?

Ten, chosen by traffic rather than at random, because the accuracy of the pages people actually read is what determines trust in the wiki. Follow each literally: run the commands, click the links, compare diagrams to the real infrastructure. The failure rate over those ten is your accuracy estimate for the space.

Should outdated documentation be deleted or archived?

Archived, as the default. Archiving removes the page from readers' paths and from search while keeping it restorable, which removes the hesitation that stalls cleanup. Deletion is for unambiguous junk: drafts, exact duplicates, pages about long-past events. Announce the archive list with a short objection window, then execute in one batch.

How often should documentation be audited?

A full audit yearly and a light quarterly pass that refreshes the inventory and re-runs spot checks on the top pages. The quarterly pass exists to catch drift early; the yearly one re-litigates ownership and runs the archive pass.