With DocStar, AI-written docs never go live on their own: your AI agent asks before it changes anything, every edit is saved as a draft, and a person on your team publishes. That gives you a natural review step. This guide shows how to use it well: let an agent draft and pre-check the changes, then review the parts only a human can judge, and publish with confidence.
Why AI-written docs need a review step
AI agents now write a lot of documentation. A coding agent can read your routes and document every endpoint, turn release notes into a changelog, or rewrite a confusing help page in minutes. That speed is the point, but it moves the risk. The hard part is no longer writing the page. It is making sure what goes live is true.
AI drafts fail in a few predictable ways:
| What goes wrong | Example | Why it matters |
|---|---|---|
| Invented details | A rate limit or field that isn't in your code | Readers and agents trust it |
| Out-of-date facts | The draft describes last month's behaviour | Support tickets, failed calls |
| Wrong scope | Internal or admin endpoints in public docs | Security and confusion |
| Tone and naming | Product names or terms used inconsistently | Your docs stop sounding like you |
| Secrets in examples | A real token pasted into a request sample | A leak, not just a typo |
In DocStar this matters even more, because the same published docs feed your docs site, llms.txt, the MCP server AI agents use to call your API, and the CLI. A wrong field in a published endpoint doesn't just confuse a reader. An agent calling your API copies it, and the call fails.
How review works in DocStar
DocStar is built so that nothing an AI writes reaches readers until someone publishes it. These are the pieces you review with:
The agent asks first. When you connect Claude, Cursor, ChatGPT or another assistant to the DocStar MCP, it shows you what it will create, change or publish and waits for your OK (how it works).
Every change starts as a draft. Drafts are visible only inside your workspace. When you or an agent edit a published page, the live site keeps showing the last published version until the page is published again.
Amber dots show what's waiting. In Settings > Publish Collection, each page has a dot: red for Unpublished, amber for Updated (live, but changed since), green for Published. Amber pages are your review queue (Publish Pages).
Two histories per page. Version History keeps every saved draft and who made the changes; Published History keeps every version that went live and who published it. You can preview and restore either (Version History).
Permissions decide who can publish. Each Admin and Member gets Read Only, Read & Write or Access Denied per collection, and only people with edit access can publish. Your agent works with exactly your permissions, never more.
AI suggestions wait for approval. AI-generated FAQs stay in a Pending tab until someone approves them, and AI changelog entries are drafts until you publish them.
The agent-first review workflow
Our main workflow is agent-first: the agent drafts the change and does the first pass of review, and a person makes the final call. Here is how to set it up.
Step 1: Connect your AI assistant to the DocStar MCP
Add https://mcp.docstar.io/mcp to Claude Code, Cursor, Codex or another assistant (or add DocStar from its connector directory). The first time it needs your workspace, you sign in to DocStar in your browser. There is no API key to copy. See Connect your AI assistant.
Step 2: Let the agent draft the change
Ask for the documentation work in plain language, as you normally would: "document the new refunds endpoint", "update the Webhooks page for the new event". The agent reads your code, writes the pages or endpoint docs, and saves them as drafts.
Step 3: Ask the agent to review its own drafts against the source
Before a person reads anything, have the agent check the drafts against the real source of truth: your code, your specs and your published docs. Paste a prompt like this:
Using the DocStar MCP, list every page and endpoint in our "Payments API" collection that has unpublished changes. For each one, compare the draft with our code in this repo and flag: (1) any field, parameter, limit or error code that isn't in the code, (2) anything the code does that the draft leaves out, (3) internal or admin endpoints that shouldn't be public, (4) anything that looks like a real token or secret in an example, and (5) product names or terms that don't match the rest of our docs. Give me a short report per page with the exact lines to fix. Don't change or publish anything yet.
The agent lists the collection's pages, reads each draft, checks it against the code it can see, and hands you a report. Because it asks before it changes anything, nothing is edited until you say so. When you agree with a fix, tell it to apply it, and the corrected text is saved as a draft again.
Step 4: The human review
This is the part only a person can do, and it is where your time should go. The agent's report already caught the mechanical problems, so you focus on judgment:
What stays private. Is every endpoint in the draft one your users should call? Admin, internal and debug routes never belong in public docs.
Is it true for users? The code says what is possible; you know what is supported, on which plans, and what is about to change.
Naming and tone. Does it sound like your product? Are features called what your UI and marketing call them?
Examples. Would a new user get a working first call from this example?
Open each amber page, read the draft, and use Version History if you want to see exactly what changed and who changed it. If a draft goes the wrong way, restore an earlier version and start again.
Step 5: Publish what you approved
When the drafts pass, publish them yourself from the page or with bulk publish, or tell the agent:
Publish the pages we just reviewed in the Payments API collection, and nothing else.
The agent shows you the list and waits for your OK. Once published, the docs site, llms.txt, MCP tools and CLI commands all use the new version. If something slips through, Published History lets you roll back to what readers saw before, then publish again.
Reviewing API docs in pull requests with GitHub Sync
If your API docs live in your repository, GitHub Sync moves review to where your team already reviews code. OpenAPI files sit in api-docs/ and Markdown pages in docs/, next to the code. When a coding agent changes an endpoint, docstar.md plus a line in AGENTS.md tells it to update the spec in the same change, so the spec change shows up in the same pull request diff as the code. Reviewers approve both together. On push, the GitHub Action sends the changed files to DocStar, with no manual import.
Two honest notes. First, with GitHub Sync the pull request is your review gate, because a push to the synced branch updates the docs. Second, the agent still has to make the doc change: DocStar does not watch your repo or compare code with docs on its own. If someone changes code without updating the spec, the docs drift until it's caught. Your AI can set the whole thing up with one prompt ("set up DocStar GitHub Sync for this repo"). We cover this in How to Keep Your API Docs in Sync with Your Code.
Keep it current: make review part of every release
Review isn't a one-off. Add a short check to your release routine so AI-written changes never pile up unreviewed:
Using the DocStar MCP, list all pages in our collections that are live but have unpublished changes, and all pending AI FAQs. For each, tell me what changed and whether it still matches the current code. Suggest which ones are ready to publish and which need a person to look.
For a deeper pass across a whole collection, see How to Audit Your Docs with an AI Agent.
If you want your team pinged when docs change, DocStar webhooks can notify your systems on events like page content updates (the payload includes the content before and after the change) and publish status changes, so you can post them to a review channel.
A quick review checklist
| Check | Who does it |
|---|---|
| Fields, params, limits and errors match the code | Agent, then human spot-check |
| Nothing the code does is missing | Agent |
| No secrets in examples | Agent, plus DocStar's warning on endpoint publish |
| Only public endpoints are documented | Human |
| Naming, tone and plan details | Human |
| Changes published, nothing else | Human approves, agent or human publishes |
When you publish an API endpoint and DocStar finds what looks like a secret, such as a token, it shows a Sensitive Information Warning so you can remove it first.
Prefer to review by hand?
Open your collection's Settings > Publish Collection, scroll to Bulk Page Publishing, and look for amber dots. Open each page, compare it with Version History, fix what you need in the editor, then tick the pages and click Publish Selected. For AI FAQs, open FAQ in the left sidebar and use the Pending tab to approve, edit or reject each suggestion.
Why teams choose DocStar
Drafts by default. AI and humans write into the same draft-then-publish flow, so nothing reaches readers by accident.
Agent does the first pass. Your AI drafts, checks its work against the code and fixes what you approve, so people spend time on judgment, not proofreading.
One review, four outputs. Approve once and your docs site,
llms.txt, MCP server and CLI all update together.Clear history and permissions. Every page keeps draft and published history, and collection permissions decide who can publish.
FAQ
Can an AI agent publish docs in DocStar without anyone approving? The agent asks before it creates, changes or publishes anything, and every edit is saved as a draft first. It also has only your permissions: if you can only read a collection, so can the agent.
How do I see what an AI agent changed on a page? Open the page's Version History. It records your draft each time an editing session ends, with when it was saved and who made the changes, and you can preview and restore any version.
What happens to the live page while a change is in review? Readers keep seeing the last published version. The page shows an amber Updated dot until you publish it again.
Do AI-generated FAQs and changelogs need review too? Yes. AI FAQs stay pending until someone approves them, and AI changelog entries are drafts until you publish them.
Can I undo a published change? Yes. Restore an earlier version from Published History; it loads into the editor as a draft, and you publish it again to make it live.
Get started free
Connect your AI assistant to DocStar, let it draft and pre-check your docs, and publish only what your team approves. Get started free.
Originally published on the DocStar blog. Try DocStar free: https://docstar.io
Top comments (0)