The README lies.
Not on purpose. It was true the day someone wrote it. Then the function got renamed, the flag got removed, the env var changed, the endpoint moved — and nobody touched the docs, because nobody's job is the docs. So the README quietly drifts away from the code, and the first person to find out is whoever copy-pastes the snippet that no longer works.
If you've ever opened a doc page, scrolled to a code block, and thought "...is this still real?" — you already know the failure mode. Docs don't rot because people are lazy. They rot because keeping them in sync is manual work that lives outside the loop where the change actually happened.
The insight: docs are a side effect of merging code
The diff already knows everything. When you merge a PR, the change is right there — the renamed function, the new param, the deleted flag. That's the exact moment the docs should update, and it's the exact moment everyone is busy doing literally anything else.
So the fix isn't "write better docs." It's: make a docs update fall out of merging code, the same way CI falls out of pushing. Treat documentation as an event-driven side effect of the merge, not a separate chore you'll get to later (you won't).
That's what I built. It's called docs-keeper, and it just launched.
How it works
docs-keeper installs as a GitHub App. No new dashboard to babysit, no docs platform to migrate to — it lives in the PR flow you already use.
When you merge a code PR, it:
- Reads the diff of what you just merged.
- Drafts grounded documentation + changelog updates from that diff.
- Runs the draft through 7 validation gates.
- Opens a docs PR for you to review.
That's it. It never auto-merges. You get a normal PR, you read it, you hit merge or you close it. Same muscle memory as reviewing a teammate's branch.
Here's roughly what shows up in your repo after a merge:
✓ merged: #482 "rename authClient → sessionClient"
└─ docs-keeper triggered on merge
reading diff… 6 files
drafting docs + changelog…
running 7 validation gates:
[1/7] grounding ........ pass
[2/7] structure ........ pass
[3/7] links ............ pass
[4/7] code-fences ...... pass
[5/7] changelog ........ pass
[6/7] style ............ pass
[7/7] safety ........... pass
→ opened PR #483 "docs: update for #482"
CHANGELOG.md | 4 ++
docs/auth.md | 12 +++---
~27s from merge → opened PR
review required · no auto-merge
You open #483, you read the diff, you decide. docs-keeper doesn't get a vote on your main branch.
The grounding gate is the whole point
The reason most people don't trust an LLM near their docs is hallucination — it'll confidently document a retryPolicy option that does not exist. So the most important of the 7 gates is the grounding gate: if the generated docs mention any identifier that isn't present in the diff, the draft gets rejected. No mystery functions, no invented params, no flags that were never shipped.
It's the difference between "AI wrote some docs" and "the docs only describe what actually changed." Grounded, not vibes.
To be clear about what I'm not claiming: this isn't magic and it isn't perfect or absolute. It can draft something you'll want to edit. That's exactly why the output is a PR you review and not a commit straight to main. The grounding gate raises the floor; you are still the ceiling.
The honest unit economics
Here's the part I think devs actually care about, so no hand-waving:
- ~$0.004 average LLM cost per doc PR. Fractions of a cent.
- ~27s from merge to an opened PR.
- 7 validation gates run before that PR ever appears.
- Free for public repos. If you're shipping in the open, this costs you nothing.
- You review every change. Always a PR, never an auto-merge.
That cost number is real because the whole thing is designed to be cheap and transparent — you can see the usage and what it cost. A doc PR that costs less than half a cent is a doc PR you can afford to get on every merge.
Where docs-keeper fits (and where it doesn't)
If you're using Mintlify or ReadMe.com — those give you lovely docs hosting and an AI writer, but you still drive the updates by hand; they're not wired to your merges. docs-keeper isn't a hosting platform; it's the thing that notices you merged and drafts the update.
If you're on docs-as-code (Docusaurus, MkDocs), that's fully manual today — docs-keeper opens the PR you'd otherwise have to remember to write.
And if your plan is "I'll just ask Copilot / paste the diff into an LLM" — sure, but that's not merge-triggered, there's no grounding gate rejecting invented identifiers, and there's no review-PR workflow. docs-keeper is the boring, automatic version of the thing you keep meaning to do.
(There's also a security angle: on Pro+, docs-keeper runs a pre-merge scan — OWASP Top 10 + secret detection — on incoming PRs and can open a review-only fix PR. Same philosophy: it opens a PR, you decide. More on that another day.)
Try it on a public repo
If you've got an open-source repo with a slightly-too-honest # TODO: docs out of date, this is the lowest-risk way to kick the tires:
- Install the docs-keeper GitHub App on a public repo (free for public repos).
- Merge a PR like you normally would.
- Watch a grounded docs PR show up in ~27s.
- Review it. Merge it or close it. You're in control either way.
Start here → https://docs-keeper.com
It just launched — tell me where it breaks
Real talk: docs-keeper is brand new. There are no testimonials, no logo wall, no "trusted by thousands" — because none of that exists yet, and I'm not going to invent it. What exists is a working bot that's been verified end-to-end in production: a merged code PR auto-opened a grounded docs PR, gates and all.
So I'd genuinely rather you try to break it than tell me it's great. Point it at a gnarly diff. See if the grounding gate holds. Tell me where the draft was wrong, where 27s wasn't enough, where a gate should've caught something and didn't. Drop it in the comments — that feedback is worth more to me right now than any star count.
The README's been lying long enough. Let's make the truth a side effect of merging.