How To Write Docs An AI Can Answer From
Connecting an assistant to your documentation exposes how the documentation is written in a way that nothing else does. Pages that a human tolerates — a heading covering four topics, a paragraph whose meaning depends on the one above it, a title naming the team rather than the subject — produce visibly worse answers, because retrieval works on passages and a passage that cannot stand alone is a passage that misleads when quoted. The good news is that the fixes are ordinary editing, and every one of them also makes the page better for the human who arrives mid-document from a search result.
One Page, One Question, One Answer
The single highest-leverage habit is scoping a page to one question a person would actually ask. 'Refund policy' is a subject. 'How do we handle a refund request after the thirty day window' is a question, and a page written to answer it will be retrieved accurately for that question and ignored for others.
The common failure is the omnibus page: a document titled after a department or a system that accumulates every decision anyone made about it. Retrieval on such a page is a coin toss, because the passage that matches your query sits beside four passages about unrelated matters and the surrounding context pulls the answer sideways.
Splitting is usually the whole fix. When a page covers three decisions, three pages covering one decision each retrieve better, read faster and are easier to keep current — an outdated section in an omnibus page tends to survive for years because nobody wants to audit the whole document to change one part.
Write Passages That Survive Being Excerpted
Assume every paragraph will be read alone, with no title above it and nothing after it. That is roughly what happens when a passage is retrieved, and it makes certain habits expensive. Pronouns pointing at the previous section, 'as mentioned above', and continuations that begin with 'this means' all lose their referent the moment the passage is lifted out.
The repair is to name the subject in the sentence rather than relying on the reader having just read something else. 'This is capped at €500' becomes 'Refunds issued without manager approval are capped at €500.' It reads as slightly more repetitive to someone going through the page top to bottom, and far clearer to everyone else, which is most readers.
The same applies to conditions. A rule stated without its scope — 'approval is required' — invites an answer that overgeneralises. Say who it applies to and when, in the same sentence as the rule, and the retrieved passage carries its own boundaries with it.
Title Pages With The Words People Use
Titles carry disproportionate weight in retrieval, and internal documentation is full of titles written from the author's point of view rather than the asker's. 'Billing operations runbook' is how the owner thinks about it; 'what to do when a customer is charged twice' is how it gets searched for.
A reliable technique is to name the page after the question that would send someone looking for it, then use the first sentence to state the answer directly. Anyone landing there gets what they came for immediately, and the retrieval layer gets a strong, unambiguous signal about what the page is for.
Where internal jargon is unavoidable, include the plain-language equivalent once in the opening lines. If the system is called Atlas internally but everyone else says invoicing, the page should contain both words, because half your team will search with each of them and so will the assistant working on their behalf.
Dates, Owners And The Trust Problem
Every page should carry a last-reviewed date and a named owner. This is not bureaucracy: it is the information a reader needs to decide how much weight to put on what they just read, and it is the only practical defence against silent staleness once an assistant is quoting documents confidently.
The named owner also solves the update question. Documentation rots because revising it is a separate task competing with real work, and 'someone should fix this' resolves to nobody. A name attached to a page turns a vague obligation into a specific one, and makes it obvious who to ask when the page and reality disagree.
The cheapest maintenance habit is to update at the moment of use. When someone answers a question in chat that the documentation should have covered, the answer is already written — moving it into the page takes seconds while the context is fresh, and that is a habit rather than a project.
A Fifteen Minute Audit Of What You Have
Take your five most-consulted documents. For each one, read the title and ask whether it is a question someone would search. Then pick three paragraphs at random, read each in isolation, and ask whether it still means what it is supposed to mean with nothing around it.
Most teams find the same three problems: titles naming systems rather than situations, paragraphs whose subject lives two paragraphs earlier, and pages covering several unrelated decisions under one banner. Fixing those on five documents takes an afternoon and improves answer quality more than adding twenty new pages would.
Then let real usage drive the rest. Questions that get asked and return nothing are a precise backlog, generated by demand instead of someone's idea of completeness, and writing along those contours keeps the knowledge base small enough that every page in it stays current.
Frequently asked questions
How should documents be structured for AI retrieval?
One page per question people actually ask, with the answer stated in the first sentence. Omnibus pages covering several unrelated decisions retrieve poorly, because the matching passage arrives surrounded by material about something else entirely.
Why do passages need to make sense alone?
Retrieval lifts paragraphs out of their page. Anything relying on 'as mentioned above', an earlier pronoun, or a condition stated two sections back loses its meaning at exactly the moment an assistant quotes it to someone.
Do we need to rewrite our existing documentation?
No. Audit the five documents people consult most, fix titles that name systems instead of situations, and split pages covering several decisions. That takes an afternoon and improves answers more than writing twenty new pages would.
How do we keep documentation from going stale?
Put a last-reviewed date and a named owner on every page, and update at the moment of use — when someone answers in chat what the docs should have covered, move that answer across while the context is still fresh.
Give your AI docs it can actually answer from
Put your team's knowledge in one place and connect it to your AI over MCP — so answers come from your documentation instead of a guess. Free for everyone right now.
Explore the knowledge base