Your engineers ship a release. The release renames a field on a request payload, changes the login flow, or adds a required header to every API call. The documentation page that describes that endpoint does not change. Nobody owns that page at most companies. A page gets updated only after someone complains.
The gap between the release and the correction is often weeks. During those weeks, every reader of the page is reading the wrong instructions. The person who finds the problem is usually a customer. That customer followed the page, wrote code against the old behavior, and got an error. Or the customer’s AI assistant read the page, wrote code against the old behavior, and handed the customer code that fails on the first request. The page was cheap to write. Keeping it correct is the harder work, and nobody is assigned to it.
The pages that drift are usually the ones written fastest. A clear page takes minutes to produce with any AI assistant. The difficulty was never drafting. The difficulty is noticing that the draft has gone wrong and fixing it before a reader meets the mistake.
Why cheap writing made the problem larger
Cheap writing moved the work from drafting to maintenance. A person can produce a clear page in minutes with any AI assistant. That same person is not watching the page when the product changes two months later.
Current documentation tools handle part of the maintenance. They regenerate an API reference from a specification. They edit prose when someone asks them to. They return a pull request. None of them watch the product for changes after the release. The step they leave to a person is the one that matters most, which is comparing what the docs say against what the product now does.
The specification covers the reference. It does not cover the prose that surrounds the reference, and the prose is where drift lives. A page written once is not read again when the product changes. The AI assistant that wrote it has moved on. The person who requested it has moved on. The page stays where it was, describing behavior that no longer exists.
What it means for docs to update themselves
Documentation that updates itself runs a check after every release. A release changes the product, so the check runs at the release. The check compares three sources against each page. Those sources are the code repository, the API specification, and the release notes. The check looks for pages that no longer match the product.
A field was renamed, so the page that names the old field no longer matches. A login flow changed, so the page that walks through the old steps no longer matches. A header was added, so the page that omits the header no longer matches. The check flags each of those pages and drafts a correction for it.
| What the release changed | The page that no longer matches |
|---|---|
| A field was renamed | The page that names the old field |
| A login flow changed | The page that walks through the old steps |
| A header was added | The page that omits the header |
The correction is a draft, not a publish. You read it before it goes live. You can approve the correction, edit it, or reject it. Nothing publishes without your approval.
When you approve a correction, the change reaches several places at once. The search index picks up the new text. The AI assistant that answers questions from your docs starts citing the corrected page. The agent-facing surfaces that machines read reflect the same change at the same time. Those surfaces include the Markdown version of the page, the llms.txt and llms-full.txt files, the model context protocol server, and the skills index. A correction reaches every reader, human and machine, in one step.
- Product sources
Repository, API specification, and release notes.
- Check the documentation
Compare the current product with each page.
- Draft and review
The agents prepare corrections for your approval.
- Publish together
Update the page, search, assistant, and agent-facing surfaces.
The pages themselves are plain files. You can read them, edit them, and export them. You keep the files even if you stop using the platform. They are not locked inside a database you cannot reach.
Where the approach stops
The check depends on the three sources being present and accurate. If a release ships without notes, or the repository and the specification disagree, the check has less to compare against. It can still flag a page that contradicts the specification. It cannot invent the product intent that nobody recorded.
Regenerating an API reference from a clean specification still handles the reference better than prose reconciliation does. A clean specification makes the reference exact, and the check makes the surrounding prose match it. The check does not replace that step. It covers the prose and the gap between the reference and the rest of the site.
The strongest case against this approach is that a person could do the same work. An engineer who reads every page after every release would catch the same drift. In practice that engineer does not exist. The release goes out, the engineer moves to the next task, and the pages wait for a complaint. The check does what that engineer would do, on a schedule that matches the release.
The approval step also means the platform does not publish instantly. A correction waits for a person. That is a feature. The cost is a delay that lasts as long as it takes you to read the draft.
What SaturnDocs does
SaturnDocs is a documentation platform built for the AI agents that now read your docs, and for the people who still do. We run the check after every release. We draft a correction for each page that no longer matches the product, and we send that draft for your approval. When you approve a change, we publish it to the page, the search index, the cited assistant, and every agent-facing surface at the same time. You supply the product context, and you approve each change before it publishes. If you want to see the check run against your next release, send us a link to your repository and your current docs, and we will show you the first set of corrections.