The doc that kept lying after the endpoint changed

We renamed a query parameter in a minor release. The code was fine, the tests were green, the changelog had a line about it, and the docs still told people to send limit. I found out two weeks later, from a support thread, and then from something worse: a coding agent that had read our public docs generated client code using the old parameter and failed in a way that looked, to the person running it, like our API was broken.

Nothing had crashed. A page was simply stale, and a stale page is now an input to other software. That changed how I think about documentation. It is not prose that sits next to the product; it is an interface that other tools consume, and it drifts on a different clock than the code.

Drift is a diff between two texts

Put two things side by side: the published documentation as it reads today, and the change that just shipped, in the form of a PR description or a changelog entry. What I need is a list of places where the first no longer describes the second.

That is a concrete, bounded task. A param rename, a removed response field, a new required header, a deprecated endpoint, a changed default, a status code that no longer applies: each of these is a claim in the docs that the change contradicts. The hard part is not spotting that something is off; it is spotting all of them, in order, without rereading a 3,000-word docs page three times and still missing the one sentence in the authentication section.

PaperDrift does that comparison: you paste published docs next to a PR or changelog, and it returns a docs-versus-change drift report ranked by severity, with a fix checklist. Paste-first, no install. The output I want is not "these files differ", it is "these four claims are now wrong, and this one will break a client".

Why severity ranking matters more than a match list

Ranking is what turns a diff into a work queue. The things that cause a hard failure for a caller or an agent go to the top: renamed parameters, removed fields, changed auth, new required inputs. The things that mislead but do not break go lower: stale defaults, outdated screenshots, wording that describes an older flow. A fix checklist attached to each item means I can hand the report to whoever owns the docs without a meeting.

I will be honest about the limit, because ranking is a judgement, not a measurement. Severity is a prioritization hint based on the two texts you supplied. It does not run your API, it does not execute the example, and it cannot know that a low-ranked sentence is the one your biggest customer relies on. I still read the report and reorder it. It is decision-support for a release review, not a live audit of your documentation site and not a certification that the docs are correct.

What paste-first does not do

This is the part I most want to be clear about, because "drift" sounds like monitoring. It is not. The tool does not crawl your docs site, connect to your repo, subscribe to pull requests, or notice anything on its own. It works on the docs text and the change text you paste into it, at the moment you paste them. If you never run it, nothing happens. If a doc changed after your paste, the report is already out of date.

That is a genuine trade-off. A live watcher would catch drift without me remembering to check, but it needs repository access, a definition of which pages matter, a way to map a code change to a doc, and a story for false alarms on every refactor. For the teams I build for, the paste-first version wins on trust and setup cost: what I see is exactly what I gave it, and I can run it once before a release without adding another always-on service.

If your last incident was "the docs said the old thing", pasting the page and the changelog into PaperDrift before the next release is a cheap way to catch it. It will not maintain the docs for you, and it will not tell you a page is broken in production. It will tell you which claims no longer match the change, which is the part I kept getting wrong by hand.

FAQ

Does it watch my repo or crawl my docs site?

No. It is paste-first. You provide the published docs and the PR or changelog; it compares those two texts. There is no live monitoring and no repo connection.

Is a high-severity item proof that a page is broken?

No. Severity is a prioritization hint from the two texts you supplied. It is decision-support, not a live audit or a guarantee that callers are failing.

Can it rewrite the docs for me?

No. It returns a severity-ranked drift report and a fix checklist. The edits are still yours to make.