Nobody decides to let the docs fall behind. It happens one reasonable merge at a time.
A developer adds a feature, writes the tests, gets a review and merges. The pull request is correct. The docs are now wrong, and nobody did anything wrong to make them so.
One small change, two things to document
Take a real example from our public example repositories. Pull request #1 in example-payments-api comes from a Jira ticket: finance reconciles refunds by reason every week and had to page through every refund to find them. The diff is small:
GET /v2/refundstakes a newreasonfilter:duplicate,fraudulentorrequested_by_customer.- A page now holds at most 50 refunds instead of 100. The default stays 20.
The first change is the point of the PR. Anyone updating the docs would add the new filter.
The second one is easy to miss. It’s one line in the code and one line in the PR description, and it’s a change in behaviour: a client that asks for 100 refunds per page now quietly gets 50. The docs page didn’t list the limit parameter at all, so there was no old number for anyone to notice and correct.
And the docs don’t live next to the code. They’re in a separate repository, example-payments-docs. Whoever reviews the code PR never sees the docs page, and whoever owns the docs never sees the code PR.
That’s the pattern: the headline change gets documented, if anything does, and the side effects quietly go stale.
Why the usual fixes don’t hold
“Update the docs in the same PR.” Not possible when the docs live in their own repository, as they often do. When they share one, it covers the page the author remembers. A checklist item in the PR template gets ticked by habit.
“The docs team will catch it.” Only if they hear about the change. Technical writers usually learn about a merge from a release note, a support ticket, or a customer whose integration stopped behaving the way the docs said.
“Generate the reference from the spec.” Worth doing where you can, and it keeps the parameter lists honest. But many reference pages are written by hand in MDX, like this one, and so are the guides, tutorials and examples that explain how to use those parameters.
“We’ll do a docs sweep before the release.” By then the context is gone. The person who made the change has moved on, and the ticket that explained why is closed.
What keeping up actually takes
Fixing drift reliably means doing four things on every merge, not once a quarter:
- Read the whole change, not just the diff: the PR description, the commits, the review comments and the ticket behind it. The ticket often says why, which the docs need.
- Find every page the change affects, wherever the docs live, including changes the PR only mentions in passing.
- Edit those pages the way your team writes them, in your framework’s format, with your terminology and your components.
- Check the result before a human looks at it: does the site build, do the links resolve, does the spec still lint?
None of this is hard for one PR. It’s hard to do for every PR, every week, forever. That’s why it slips.
How DocFit does it
This is the job DocFit was built for. It’s a GitHub App: when a pull request merges, it reads the PR and its linked ticket, finds the docs pages the change affects, edits them and builds and lints the result. Then it opens a docs pull request for your team to review. It never merges anything itself.
For the pull request above, DocFit read the code PR and Jira ticket KAN-4, and opened pull request #1 in example-payments-docs, in the docs repository. It added the reason filter with its three values to the refunds page, and documented limit: 1 to 50, default 20, larger pages capped at 50. All checks passed, and the PR body lists the page with the reason it changed. Then it was merged like any other PR.
See how DocFit works, or start free below and see what it would have changed in your docs for your last few merged pull requests.