Should AI Write Your Product Documentation?

Somebody on your team has already tried it. They pasted a request handler into a chat window, asked for a reference page, and got back something clean, well-organised and mostly right. The word carrying the weight in that sentence is “mostly”, and no amount of prompt engineering takes it out. It is not a quality problem you can iterate away. It is a category problem.

Here is the position this piece defends. A model can draft documentation. It cannot hold authority over documentation. Those are two different jobs, and nearly every argument about AI documentation goes sideways because teams treat them as one. Split them apart and the question changes from “should we use this” into “what is the review contract”, which is a question that actually has an answer.

The failure mode is not gibberish. Current models do not write gibberish. They write fluent, confident, correctly formatted prose describing a product that does not quite exist: a parameter renamed two releases ago, a default that flipped, an endpoint that returns 202 where the page says 200, a permission that used to be optional. Wrong documentation looks exactly like right documentation. That is what makes this different from every other place a generated draft gets used.

Nobody proofreads a page that reads well.

Drafting and authority are different jobs

Drafting is producing a plausible arrangement of words on a topic. Authority is the claim that those words are true of this product, in this version, today, staked by a person who can be found and asked about it in six months. The first is a language problem. The second is not a language problem at all, which is why better models do not move it.

Models are very good at the first and structurally incapable of the second, in roughly the way a spellchecker is incapable of knowing which word you meant. A model has read an enormous quantity of documentation. It has never once used your product.

So the working rule is short: a draft carries no signature until a person puts one on it. The signature is what readers are trusting when they follow step four of a guide into their production account. It was never the prose.

Teams that hold that line get most of the speed and almost none of the risk. Teams that blur it end up publishing confident sentences nobody wrote and nobody checked, which is a worse position than having no documentation at all. Missing pages at least tell the truth about themselves.

Where a model genuinely earns its place

The case for using a model here is stronger than sceptics allow, and it has nothing to do with typing speed. The wins are structural, and they arrive before a single sentence of final prose is written.

Structure and coverage

Most documentation is bad structurally long before it is bad factually. Pages answer the question the writer found interesting rather than the one the reader arrived with. Reference sections list the happy path and skip the error cases. Getting-started guides quietly assume an account, a key and a local environment that already work. A model is good at catching those gaps, because gap-spotting is pattern comparison against a very large set of well-formed examples, and that is precisely the operation it performs.

• Outlines before prose. Ask for the page plan and the specific question each section answers, then argue with it. Most of the value sits here, and it takes minutes.
• Coverage checks. Hand it the finished page plus the schema and ask what a reader could reasonably want that the page does not address.
• Reference scaffolding. Turning a type definition or a schema file into tables and stub prose is mechanical work with a checkable output.
• Consistency passes. Enforcing one term for one concept across a set written over four years by six people who each had a favourite word.
• Second-language drafts. A translated draft reviewed by a speaker beats no translation, as long as the review is actually scheduled rather than hoped for.
• The tedium. Changelog lines into release-note prose, parameter lists into tables, a pile of headings into a navigation tree.

Consistency across a set

Terminology drift is the quiet tax on any documentation set older than a year. One page says workspace, another says project, a third says account, and all three mean the same object. Readers never report this. They just stop trusting the docs and open a ticket instead. A model is genuinely strong here, because the task is a text transformation with a fixed target, and the target can be your own glossary. Treated properly, documentation is a content channel with compounding value rather than an obligation, and consistency is the cheapest improvement available to it.

What a model cannot know about your product

Correctness against the running system

Give a model the whole repository and it still does not know what your product does. It knows what the code in that snapshot appears to do. It does not know about the migration that ran on Tuesday, the flag that makes the documented default false for half your accounts, the proxy that rewrites a header before the handler ever sees it, or the endpoint everyone stopped using internally and nobody removed.

The gap is not knowledge. It is observation. Documentation is a claim about behaviour, and behaviour is only knowable by running the thing and watching what comes back.

Confidence with no hesitation in it

The second limit is worse, because it is invisible. A human writer who is unsure hedges, or leaves a note in square brackets, or walks over and asks. That hesitation is information, and reviewers read it without being told to. A model has no hesitation to express. It fills the gap with the most probable continuation, in the same register and the same tone as the parts it got exactly right.

This is the same problem in different clothes as an assistant answering a pricing question it was never given the answer to. We set out the containment pattern in keeping an assistant from promising something you do not sell, and the mechanism transfers directly. Bound what may be claimed, then verify the bounded set. Do not try to detect confidence, because there is none to detect.

A model can write the sentence. It cannot be the person who answers for the sentence when a customer follows it into production.

The review contract, in six lines

So write it down. Not a policy document, not a governance framework. Six lines in the contributing guide that state who may publish what, and what has to be true before they do.

1. Name the claim class. Every change states what kind of claims it makes: conceptual, procedural, reference, or consequential — meaning money, data or access.
2. Attach the evidence. A procedural page ships with the record of someone completing it end to end. A reference page ships with the schema it was generated from.
3. Assign a reviewer who owns the product surface, not one who owns writing. Prose quality is the easy half and the model already did most of it.
4. Reject on unverifiable, not on wrong. If the reviewer cannot check a sentence, it comes out. This single rule removes more bad documentation than fact-checking ever does.
5. Record the version. The build, tag or commit the page was verified against. Without it, nobody can later tell stale from wrong, and those need different fixes.
6. Sign it. A named person, in the commit or the workflow. Never a team alias.

That is the entire contract. Note what it does to your costs: reviewing a generated draft takes more of a reviewer’s time than reviewing human prose, not less, because there are no natural signals of doubt to guide attention. Anyone selling you the opposite is selling you the risk with the saving.

Not every page deserves the same gate

Risk is not evenly distributed across a documentation set, so the gate should not be either. This is the split we work to.

Read down the last column. Every entry describes an act of observation rather than an act of reading. That is the whole point of the table, and it is the part teams skip when they are pleased with how fast the drafts arrived.

Where the draft lives decides whether review happens

A review contract the system does not enforce is a review contract that happens when nobody is busy, which is never. Good intentions lose to a release week every time. So the place a draft physically sits matters more than the wording of the policy above it.

That is the strongest practical argument for keeping documentation in the same repository as the product it describes. The review gate is the pull request, the diff is legible, the reviewer is already in the tool, and the version the page was verified against is recorded at no extra cost. A structured workspace can sit on top without giving any of that up: Acrosite works this way, generating the files, committing them to GitHub and triggering the configured deployment, so writers get an ordinary interface while the history stays in version control.

Our parent company has written on both halves of this: where drafts live and what stops them on the storage and gate question, and the reviewer’s pass on what a reviewer should actually do with a draft they did not write.

Pages where the rule tightens

Some pages never get a lighter gate. Anything describing billing, permissions, retention, deletion, security configuration or a migration path is consequential: a reader who follows it incorrectly loses money, access or data. “The draft was generated” is not a defence that survives the conversation afterwards, and it should not be.

In-product copy belongs in the same category and gets forgotten more often, because it does not live in the docs folder. Error messages, confirmation dialogs and especially empty states are documentation that happens to render inside the application. They describe behaviour, and they are read at the exact moment a reader can least afford a wrong instruction. If you are already rewriting them as part of ongoing product improvement work, put them under the same contract as the documentation site.

There is a newer reason to care. Documentation is increasingly consumed through an assistant rather than a page, sometimes yours and sometimes someone else’s, and an assistant will cheerfully assemble one answer from three pages that were each only slightly stale. We looked at the front-door version of this in whether an assistant can replace your contact form. The short version: retrieval amplifies whatever accuracy you already had, in both directions, and it does so without telling you which direction it went.

The cost nobody puts on the plan

Generation is cheap, and that is the trap. A weekend of prompting can produce four hundred pages, and four hundred pages is not an asset. It is a maintenance surface that has to be re-verified every time the product moves, by people who did not write it and cannot remember what it claimed. The bill arrives late and it arrives as confusion rather than as an invoice.

This has the same shape as an automation nobody owns: cheap to create, expensive to keep true, invisible on every budget line until it fails in front of a customer. The ownership argument is in the standing cost of an automation nobody owns, and the design of the checking step itself is in designing a review step that catches errors. Both apply here with no modification at all.

Where we would start on Monday

Use a model for outlines, coverage checks, reference scaffolding and consistency passes. Do not use it for the sentence that tells a reader what will happen when they click the button. Verify by running, not by reading. Sign what you publish, with a name and a version. That is four rules, and a small team can adopt all four in an afternoon.

The advice reverses in one place, and it deserves naming honestly. Internal documentation with a short half-life, read by people who can check it against the running system in thirty seconds and correct it in place, does not need this ceremony. A generated runbook draft that gets fixed on first use is a perfectly good trade. The contract exists because external readers cannot correct what they cannot see, and they will not tell you it was wrong. They will simply leave.

If you are wiring generation into a pipeline rather than a habit, the questions are ordinary AI development and integration questions: what goes into the context, what is bounded, what fails closed, and who gets told when it does. If you have a documentation set that has quietly stopped being true, tell us what it covers and how often the product underneath it moves.