Writing Docs for Readers Who Are Machines
Structuring a help centre for AI answer engines: what llms.txt does, why chunk-friendly headings matter, and how to audit what models currently say about you.
Ask any of the major assistants how to do something specific in your product. Not what your product is - they will manage that from your homepage - but a real task, three levels in, the kind of thing your help centre exists to answer. Then read what comes back and decide whether you would have shipped it.
For most companies the answer is somewhere between "vague" and "confidently describing a feature we removed in 2024". That output is now a meaningful share of how people learn to use software, and almost nobody is treating it as a surface they own.
The shape of the traffic changed
The old model was a search result: ten links, a human clicks one, lands on your page, reads your words in your layout. You controlled the destination and you could measure the visit.
The new model is a synthesis. Someone asks a question, a model reads several sources including yours, and produces an answer the person acts on without ever arriving. You are no longer the destination. You are an input, and whether you are a good input depends on properties that have nothing to do with how the page looks.
This is uncomfortable because the usual analytics go dark. A model that read your documentation and answered correctly generates no session, no pageview and no conversion event. The work happened, the value landed, and your dashboard shows nothing. Judging documentation by traffic was always imperfect. It is now actively misleading.
What makes a page a good input
Everything that matters here is structural, and most of it is unglamorous.
Self-contained sections. Retrieval works on chunks, not pages. A section that begins "Once you have done the above" is useless out of context, and out of context is exactly where it will be read. Every ## section should make sense to someone who has seen only that section.
Literal terminology. Models match on the words that are present. If your product calls it a "workspace" and your docs call it a "project" because an old version did, you have halved your retrievability for no benefit. Pick the name in the UI and use it every time, even when repetition feels clumsy.
Answers before context. Lead each section with the answer and follow with the caveats. Prose that builds to a conclusion is good writing and bad chunking - if the payload is in the last paragraph, a chunk that stops earlier carries none of it.
Explicit negatives. Say what the product does not do. Models are far more likely to invent a capability than to invent a limitation, so a page that states plainly "there is no CSV export" is doing more to prevent a wrong answer than any amount of accurate positive documentation.
A machine-readable index. llms.txt is a plain markdown file at your root listing your key documentation URLs with one-line descriptions. It is a low-effort, no-downside way to tell a crawler where the useful pages are instead of hoping it works that out. We serve one automatically for every help centre.
Nobody knows how much of this matters
I have no idea how much of this matters, and neither does anyone else claiming otherwise.
The honest position is that the retrieval behaviour of these systems is unpublished, changes without notice, and differs between providers. Advice about chunk-friendly structure is inference from how retrieval generally works, not from documented behaviour of any specific product. Anyone selling you an "AI SEO audit" with a score out of a hundred has invented the scoring.
What saves the advice is that all of it is independently good. Self-contained sections help humans skimming. Consistent terminology helps search and reduces support confusion. Stating what you do not do prevents bad-fit signups. Answers-first is just better technical writing. If the AI angle turns out to be overstated, you have still improved your documentation. That asymmetry is why I am comfortable recommending it while being clear that the mechanism is guesswork.
The one thing I would not do is restructure a working help centre wholesale on this basis. Apply it to what you write next.
An audit you can run this week
Pick your ten most important tasks. Ask three different assistants how to do each one. Log whether the answer was right, vague, or invented.
That table is a more accurate picture of your documentation's reach than your analytics dashboard, and it takes about an hour.
About the Author
Simon Moxon has been building SaaS companies since 2009. He's scaled teams to 20+ people, hit £2m ARR, and learned most of the lessons the hard way. Now he's building SupportPages.io - help docs that write themselves when you ship code. He writes about what's changed in SaaS and what hasn't.