Docs drift is the slow divergence between what your code actually does and what your documentation claims it does. Every merged change that touches behavior is a chance for the docs to fall a little further behind.
It rarely happens all at once. It accumulates, one PR at a time, until the README describes a system that no longer exists.
A small example
You rename a parameter and update the signature:
-def charge(amount):
+def charge(amount, currency):
The code is correct. CI is green. The PR merges. But the README still says:
Call
charge(amount)to bill the default currency.
That line is now wrong. Nothing failed, nothing flagged it, and the doc will sit there being wrong until someone trips over it.
Why it happens at review time
The moment a change is reviewed and merged is exactly when docs drift is created. Three things line up against you:
- Docs live somewhere else. The code change is in the diff. The doc that describes it is in another file, often another directory. The author updates what is in front of them.
- Reviewers focus on code. A PR review is about correctness, design, and tests. Catching a stale sentence three files away is not what reviewers are looking for, so it slips through.
- Context is highest right now and gone later. The author knows precisely what changed and why. A week later, that context is gone, and fixing the doc means re-deriving it from scratch.
So the cheapest possible moment to fix the doc is the one moment nobody is looking at the doc.
The cost adds up
A single stale line is harmless. The problem is compounding.
- Onboarding slows. New teammates follow the docs, hit behavior that does not match, and stop trusting them.
- Trust collapses. Once people learn the docs are sometimes wrong, they stop reading them and start reading source instead. Now the docs are dead weight.
- Support load rises. Wrong docs generate questions, bug reports that are not bugs, and integration mistakes from anyone consuming your API.
- It is hardest to fix in bulk. A doc audit means re-reading the whole codebase to figure out which sentences are still true. That is a project, not a chore.
The fix is to move the check to where drift is born
If drift is created at review time, that is where it should be caught. Not in a quarterly doc sweep, not when a user complains, but in the PR that introduced the change, while the author still has the context to fix it in seconds.
That means treating docs the way you treat code: something that gets checked as part of the change, in the same review, by something that reads the diff and notices when a documented thing moved.
That is the gap ZAR is built to close. It reads the code change and the docs together, in the PR, and proposes the minimal patch to keep them in sync. Drift stops compounding because it never gets a chance to ship.