How do you detect documentation drift?

You do not detect a stale documentation page by rereading it. You start from the code changes of the period and work back to the pages they invalidated. Reading in that direction finds in minutes what a full review misses for months, for a simple reason: a diff knows what it changed, and a page has no idea it has aged.

This article gives you the audit to run today, names what it will not catch, and describes the continuous detection that takes over. For the why of drift and its four shapes, the reference article covers the ground; this one is about spotting it.

The short answer: reverse the direction of reading

Conventional detection starts from the text. You open a page and ask whether it is still true. It fails because it asks a reader to notice missing information.

Detection that works starts from the code. Take the span of deploys since a page was written, read the diffs in that span, and keep the ones that touch what the page describes. What the page claims enters the reasoning only at the end, to settle the verdict. It is the difference between searching the whole house for your keys and remembering where you put them down.

Why a full review finds almost nothing

Three mechanisms, and none of them yields to more attention.

You reread what you already suspect. A reviewer opens the pages they heard about in a meeting or a ticket first. Those are the ones whose drift is already known. Everything else passes by default.

Half-truths survive a reading. A sentence like "webhooks are retried three times" stays literally true after you add exponential backoff and a signature. It is true and unusable. No reviewer fixes it, because there is nothing wrong in what they are reading — the fault lies in what is absent.

An absence cannot be reread. The feature shipped last month and never documented has no page to open. An audit that walks the list of existing pages cannot, by design, run into a page that does not exist.

So reviews catch the easy case, the visible one, and leave the two that cost.

The manual audit, in three passes

It fits in half a day and needs no tooling. Run it once: it produces a number, and the number drives the decisions.

Pass 1 — pick pages by traffic, not by intuition. Pull the ten most-viewed pages of your help center over the last 90 days, plus the three most-used support macros. That is where drift costs you, because that is where it gets read. Note each page's real last-modified date, not the one on display.

Pass 2 — ask every page the same question, in the direction of the diffs. For a page last touched on 14 June, the question is not "is this page correct?" but: which code changes since 14 June touch what this page describes? Read the diffs over that span on the relevant files — not the commit messages, the diffs: a message says "fix export", a diff says the separator is now something else. File each verdict in one of three buckets: correct, stale, incomplete.

Pass 3 — compute the rate, then sort by cost. Your drift rate is the number of pages that are not "correct" divided by the number audited. On an illustrative sample of thirteen pages, six stale and two incomplete give 8/13, or 62%. The number itself is useful once; what is useful is putting it on the table. Then sort by views × severity, and you have this week's rewrite queue.

Budget nine to twelve minutes per page with the repository at hand. Thirteen pages fit in a morning, then. Three hundred pages do not, and that is the real output of the exercise.

The three blind spots of the manual protocol

It is useful. It is not sufficient. What it will not see:

• Everything outside the top 10. A help center's long tail holds the integration guides — the ones integrators and agents actually read. A sample never covers them.
• Surfaces that are not pages. Saved support replies, email templates, the bot's knowledge base, marketing pages that describe an option. They drift at the same speed and nobody audits them.
• The delay. A quarterly audit gives a false page a full quarter to do its work. Between two passes your drift rate is not known; it is assumed.

The bottleneck is not rewriting, it is detection. Writing a corrected page takes twenty minutes. Knowing which page to correct takes a quarter.

"What did this release just make false?"

That is the question continuous detection makes possible, and it gets asked at every deploy rather than once a quarter. The answer is a list: the pages, macros and sections whose subject moved in this release's diffs, each with the commit that concerns it.

Put to an expert wired into the code, it returns something like: "this release touches three documented surfaces — the export format (import guide, section 2), the webhook retry delay (integrations page and the Webhook not received macro), and a scheduling option added yesterday that is documented nowhere." The third item is the one no review would ever produce, since it points at a page that does not exist.

DeployIt reads your actual code (resynced at every push), your git history (commits and diffs) and your customer data through its own MCP servers, and checks the code before it asserts anything. Detection then becomes a by-product of deploying: the help center derived from the code recomputes the part that moved, and what remains on the list is what a human should handle. For agents, the same source is exposed through one MCP server per project, in early access via the design partner program: an agent wired into it queries the code rather than a text, and its answer is dated at the moment of the question, not at the moment of writing.

This is the loop described in keeping your help center in sync with every release, taken here at its first link. And it is the same git source that feeds the changelog generated from history: one change, several surfaces that follow from it.

"A grep on technical terms plus a CI rule is enough"

It is the most serious in-house method, and it catches a whole family of cases. A script that searches the docs for function identifiers, parameter names and endpoints touched by a diff will flag pages to review. If you have it, keep it.

Its two limits come down to vocabulary. First: documentation written for customers almost never quotes the identifiers in the code. A page that says "your file opens in Excel" contains neither csv_separator nor the module name, so the grep never sees it. Second: a behaviour change with no rename leaves no lexical trace at all. A default value going from 3 to 5 edits one line without touching a single searched term.

That is where the difference sits. A grep compares strings; reading diffs compares behaviours described in plain language against behaviours observed in code. It is also what lets you answer "why did this behaviour change?" from the commit's intent, where a CI rule can only raise a flag.

"So this tool reads my whole repository"

It does read it: that is the only way to compare a text against a behaviour. Three boundaries frame that reading. GitHub access is read-only and revocable at any time. There is one server per project, blind to the others.

And what comes out is never code: it is answers and derived pages. A reader learns that the export separator changed; they learn nothing about how your pipeline is written.

The comparison with neighbouring tools comes down to scope. Context7 and DeepWiki cover libraries and public repositories. Mintlify generates an MCP server from your written docs, so from the very text that drifts — the thing this article is trying to detect. DeployIt covers your private product, derived from the code itself, fresh at every deploy.

Mini-FAQ

How often should the manual audit run? Once, to get the number. After that the question is no longer frequency but moving to detection triggered by deploys: they are what creates drift, so they are what should report it.

Is a 60% drift rate abnormal? It is unremarkable for a knowledge base older than a year with no derivation in place. The number is not a judgement on the team; it measures the gap between a deploy cadence and a review cadence.

Can you detect drift without touching the code? Partly: recurring tickets and repeated support questions are a delayed signal. You learn a page was wrong because a customer got it wrong. The cost has already been paid.

What about hand-written pages, the ones explaining the why? They drift less and they stay yours. Derivation takes on the what and the how, the part that moves at every deploy.

How do you find a feature that is documented nowhere? By starting from the code: the period's diffs contain the feature, the page index does not. Absence is found by difference, never by reading.

What to take away

A page does not know it is false, and a reviewer cannot guess it on the page's behalf. Detection comes down to one reversal: start from the period's diffs, work back to the pages concerned, and treat absence as a result on a par with error. Run the three-pass protocol once this week — the rate it gives you will say whether a quarterly review is still a plan.

DeployIt is free during early access; paid plans arrive in January 2027. Agents plug into that same source through the design partner program, which is taking applications.