What is documentation drift?

Documentation drift is the state where written documentation no longer accurately describes the system it claims to document. The code is the living system; the docs are a snapshot that aged poorly.

Drift is not the same as missing docs. Missing docs were never written. Drifted docs were written once - often carefully - and then the product moved on without them. Both waste onboarding time; drift is worse because the page still looks authoritative.

Teams often treat every bad wiki page as “we need more docs.” That mixes two problems and produces the wrong fix.

Missing documentation is a coverage gap: no page exists for auth, billing, or the public API. The remedy is to write the first version, preferably next to the code.

Documentation drift - also called docs drift or stale documentation - is a truth gap. The page exists, people still send it to new hires, and it describes last quarter’s system. The remedy is detection plus a cheap way to correct the page, not another blank template.

A doc day that rewrites the wiki by hand does not hold. The page is stale again the next time a service is renamed. Fixing stale docs is a loop, not a project:

Moxie Docs' own blog shows how a small implementation change can invalidate a useful guide. Markdown files remain in the repository for authoring, but published article pages load their content from a database. Older instructions still described committing a Markdown file as sufficient to publish it.

The runtime evidence is the article lookup. This excerpt is simplified to show the relevant behavior:

const article = await database
  .from("blog_articles")
  .select("slug, markdown, status")
  .eq("slug", slug)
  .neq("status", "unpublished")
  .maybeSingle();

The finding is specific: editing an authoring file does not update the database row that the live page reads. The corresponding documentation correction is small:

- Merge the Markdown file to publish the post on the site.
+ Markdown files are authoring inputs, not the live catalog.
+ Publish the reviewed article through the admin CMS or an explicit import.
+ Verify the live article after publication.

The review connects three pieces of evidence: the runtime read path, the incorrect publishing instruction, and the corrected guide. Keeping that evidence in the documentation PR lets the reviewer verify the fix without reconstructing the whole migration.

Copy this into your PR template and replace the examples with the docs your team actually maintains. A checked box records a review; it does not prove that the documentation is correct.

## Documentation impact
- [ ] I checked setup steps, commands, defaults, and API behavior affected by this change.
- [ ] I named the documentation pages that describe the changed behavior.
- [ ] I updated those pages, or explained why their current wording remains correct.
- [ ] I tried the documented command or example where practical.
- [ ] I checked agent instructions and diagrams for the same outdated assumption.

Evidence: [source path or diff] -> [documentation path and section]

A path-based CI check can remind reviewers when code changed without docs. It cannot tell whether a changed paragraph is true or whether a behavior change needs no documentation. For checks tied to repository evidence and reviewable updates, see Moxie Docs documentation drift detection and PR documentation checks.

Drift is structural, not a moral failing of the team. Code and docs usually live in different places, ship on different cadences, and get different rewards. Merging a feature is visible. Updating the wiki is optional and rarely reviewed.

Common causes stack on top of each other:

You do not need a full audit to know drift is present. These signals show up early:

Most teams start with process: doc checklists on PRs, quarterly doc days, or a wiki owner. Those help for a while, then lose to delivery pressure.

Stronger approaches couple docs to the source of truth:

Useful detection is specific. "Docs might be outdated" is noise. Better signals look like: