Doc Archaeology
Parent: Writing and Documentation · Published reference · snapshot 2026-09-08 · skill content-ingestion-extraction/references/doc-archaeology.md
↓ Facts as markdownall context files
Excavate aging documents for staleness, dead links, process drift, phantom dependencies, and obsolete examples.
These notes link each claim to its source. Some citations identify archived research reports that are no longer hosted on this site. A published reference means the content is available; it does not certify independent review or accuracy.Read the editorial policy and follow the sources before relying on a claim.
Doc Archaeology
- Excavate aging documents for staleness, dead links, process drift, phantom dependencies, and obsolete examples. [archived source: https://llms-explorer.com/sources/mdb-context-hub/doc-archaeology/#doc-archaeology]
Five categories of doc decay
- Stale Facts - claims about state-of-the-world that have changed [archived source: https://llms-explorer.com/sources/mdb-context-hub/doc-archaeology/#five-categories-of-doc-decay]
- Dead Links - URLs that 404, redirect to unrelated destinations [archived source: https://llms-explorer.com/sources/mdb-context-hub/doc-archaeology/#five-categories-of-doc-decay]
- Drift from Current Process - procedures that no longer reflect actual practice [archived source: https://llms-explorer.com/sources/mdb-context-hub/doc-archaeology/#five-categories-of-doc-decay]
- Phantom Dependencies - scripts, files, tools, people that no longer exist [archived source: https://llms-explorer.com/sources/mdb-context-hub/doc-archaeology/#five-categories-of-doc-decay]
- Obsolete Examples - code snippets reflecting prior API or UI [archived source: https://llms-explorer.com/sources/mdb-context-hub/doc-archaeology/#five-categories-of-doc-decay]
Five-pass workflow
- Last-Updated Lens - estimate age, catalog time-sensitive claims, set decay risk (low/medium/high) [archived source: https://llms-explorer.com/sources/mdb-context-hub/doc-archaeology/#five-pass-workflow]
- Fact-Check Pass - verify each claim against current state [archived source: https://llms-explorer.com/sources/mdb-context-hub/doc-archaeology/#five-pass-workflow]
- Link-Check Pass - verify every URL; flag auth-gated as "unverified" [archived source: https://llms-explorer.com/sources/mdb-context-hub/doc-archaeology/#five-pass-workflow]
- Process-Check Pass - verify procedures against current practice at step level [archived source: https://llms-explorer.com/sources/mdb-context-hub/doc-archaeology/#five-pass-workflow]
- Dependency-Check Pass - check scripts, files, tools, channels, people [archived source: https://llms-explorer.com/sources/mdb-context-hub/doc-archaeology/#five-pass-workflow]
Findings table
- Severity: Critical/Misleading → High/Outdated → Medium/Cosmetic → Low/Historical [archived source: https://llms-explorer.com/sources/mdb-context-hub/doc-archaeology/#findings-table]
Salvage decisions
- Update in place - targeted fixes; structure is sound [archived source: https://llms-explorer.com/sources/mdb-context-hub/doc-archaeology/#salvage-decisions]
- Restructure and refresh - major rewrites needed [archived source: https://llms-explorer.com/sources/mdb-context-hub/doc-archaeology/#salvage-decisions]
- Deprecate with pointer - superseded, add deprecation banner [archived source: https://llms-explorer.com/sources/mdb-context-hub/doc-archaeology/#salvage-decisions]
- Archive - historical state; remove from search [archived source: https://llms-explorer.com/sources/mdb-context-hub/doc-archaeology/#salvage-decisions]
- Delete - fully phantom, all claims stale [archived source: https://llms-explorer.com/sources/mdb-context-hub/doc-archaeology/#salvage-decisions]
Anti-patterns
- Noting a doc is old without running any passes (ostrich mode) [archived source: https://llms-explorer.com/sources/mdb-context-hub/doc-archaeology/#anti-patterns]
- Rewriting when targeted refresh would suffice [archived source: https://llms-explorer.com/sources/mdb-context-hub/doc-archaeology/#anti-patterns]
- Deleting load-bearing historical context [archived source: https://llms-explorer.com/sources/mdb-context-hub/doc-archaeology/#anti-patterns]
- Treating unverifiable as confirmed [archived source: https://llms-explorer.com/sources/mdb-context-hub/doc-archaeology/#anti-patterns]
Where this helps
- Auditing an old runbook or onboarding doc before a team relies on it during an incident, to catch dead links, phantom dependencies, and obsolete examples before they cause real damage. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.
- Deciding whether to archive, rewrite, or leave alone a legacy doc during a documentation cleanup sprint, using explicit salvage-decision criteria instead of gut feel. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.
- Investigating why a "known good" setup guide keeps failing for new hires, which often traces back to process drift the doc never captured. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.
- Preparing a docs repo for a migration or major version bump, where stale examples and phantom dependencies need to be found systematically rather than one broken report at a time. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.
How to apply this
- Run the five-pass workflow in order rather than trying to fix everything on a first read-through, since staleness, dead links, drift, phantom dependencies, and obsolete examples each need a dedicated pass to catch reliably. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.
- Log every finding in a structured findings table — what's wrong, where, severity — before deciding what to do with it, so triage happens after full discovery rather than doc by doc in isolation. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.
- Apply explicit salvage-decision criteria (rewrite, archive, delete, flag-for-owner) rather than defaulting to "just leave it," which is how stale docs accumulate in the first place. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.
- Check for phantom dependencies specifically — references to tools, services, or steps that no longer exist — since these are the failures that cost a reader the most time before they realize the doc is wrong. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.
Common mistakes
- Fixing individual broken links or examples as you happen to notice them instead of running a structured pass, which leaves the rest of the same decay category undetected. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.
- Archiving a doc because it looks old without checking whether it's still the only documentation for a still-active process, silently breaking someone else's workflow. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.
- Rewriting a doc's content without first confirming which of the five decay categories actually caused the problem, which risks fixing the symptom (an outdated example) while leaving the root cause (process drift) untouched. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.
- Auditing docs in isolation from their actual usage, deprioritizing a heavily-referenced doc with minor issues while over-investing in a rarely-read doc with cosmetic problems. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.
Known issues
- Doc archaeology is inherently a point-in-time audit; without a recurring cadence or an owner, the same categories of decay creep back in within months. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.
- Dead-link and phantom-dependency detection can be automated, but detecting process drift, where the doc's steps no longer match how the team actually works, usually still requires a human who knows current practice. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.
- A five-pass audit takes real time proportional to the size of the doc corpus, so it doesn't scale well as a fully manual process for large, sprawling documentation sets. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.
- Salvage decisions are judgment calls — reasonable auditors can disagree on whether a doc is worth rewriting versus archiving, especially when usage data on who actually reads it isn't available. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.
Children
- Five decay categories (stale facts, dead links, drift, phantom dependencies, obsolete examples) (frontier)
- Last-updated lens pass (frontier)
- Link verification pass (frontier)
- Process-currency pass (frontier)
- Dependency audit pass (frontier)
- Example validation pass (frontier)
- Salvage decision (update / restructure / deprecate / archive / delete) (frontier)
- Semantic decay and knowledge drift (frontier)
- Diátaxis process-drift theory (how-to guides rot fastest) (frontier)
- Nielsen documentation maintenance research (frontier)
Frontier under this node: Dependency audit pass, Diátaxis process-drift theory (how-to guides rot fastest), Example validation pass, Five decay categories (stale facts, dead links, drift, phantom dependencies, obsolete examples), Last-updated lens pass, Link verification pass, Nielsen documentation maintenance research, Process-currency pass, Salvage decision (update / restructure / deprecate / archive / delete), Semantic decay and knowledge drift