How to write documentation an AI can actually answer from

There is a document in every company that answers everything and helps nobody. Three thousand words, written over two years, with the refund rule in paragraph eleven and the exception to it in paragraph nineteen.

A person can work with that, because a person skims. An assistant cannot, because it never sees the document. It sees a piece of it, chosen by a machine that was looking for one specific thing.

The unit is the passage, not the page

Before anything is answered, your documents are split into chunks and indexed. A question then retrieves a handful of those chunks, and the model writes an answer from what came back. Nothing else from the page travels with them.

Here is the same answer stored two ways.

Same facts, same company, same assistant. The difference is entirely in how the text was arranged before anybody asked anything.

Six habits that do the work

None of these is a rewrite. They are decisions you make while writing anyway.

• One page, one question. A page called "Orders" holds eleven answers badly. Eleven short pages each hold one well, and they are easier for humans to maintain too.
• Headings that read like questions. They are the strongest signal a chunk carries, and they survive the split. "Changing a delivery address" beats "Address changes and other amendments".
• Repeat the subject. A passage that starts with "You can change it within 2 hours" has lost what "it" was. Write the noun again, even when it feels redundant two lines below the heading.
• Keep the rule and its exception together. If the exception is three paragraphs away, they land in different chunks and the answer loses one of them.
• Numbers with their unit and their scope. "2 hours from the time the order is placed" rather than "2 hours".
• Write the awkward answers down. The ones nobody published: what happens if you are late, who pays what, what you will not do. Those are the questions people actually ask an assistant, precisely because they could not find them.

What to do with formats that resist

Long PDFs, tables and screenshot-only instructions are where good content goes to be unfindable.

How to know whether it worked

Not by reading your documents again. By asking the assistant your twenty real questions and reading what it retrieved, not only what it said.

Three patterns tell you what to fix. A right answer from a low-scoring passage means the content exists in the wrong shape. The same passage coming back for different questions means that page is doing too many jobs. And a confident answer citing a page that is out of date means your problem is not writing at all, it is that nobody owns the update.

Questions people ask

Pick one page that tries to answer everything, split it into the four questions it actually answers, and ask the assistant those four. The scores will tell you the rest.