AI assistants cite documentation that answers a question inside a single self-contained passage, states facts in the words readers actually use, and can be read without running JavaScript. Almost every other tactic is downstream of those three.
This matters because a growing share of documentation traffic never reaches a search results page. Someone asks an assistant how to rotate an API key, and either your page is the one quoted back to them or somebody else’s is.
How do AI assistants actually read documentation?
Whether the assistant is browsing live or drawing on an index, the pipeline is roughly the same. Your page is fetched, stripped to text, and cut into chunks of a few hundred words. Chunks are matched against the question. A handful of the closest matches go to the model, which writes an answer and attributes it.
Two consequences fall straight out of that, and they are the whole of this article:
- The chunk is the unit of retrieval, not the page. A section that only makes sense after reading three sections above it will be retrieved alone, misunderstood, and skipped.
- Text that is not in the HTML does not exist. Content assembled by a script after load is frequently not seen at all.
Write every section as if it will be read by someone who has never seen the rest of the page. Increasingly, it will be.
Put the answer in the first three sentences
Under each heading, state the answer before the context. Not “There are several factors to consider when choosing a retention period…” but “The default retention period is 30 days. You can set any value between 1 and 365 days on paid plans.” The qualifications go after.
This is old newspaper practice, the inverted pyramid, and it works for the same reason it always did. A reader who scans and a retrieval system that ranks by relevance are both looking for the same thing: the sentence that contains the answer, near the top.
Make headings the questions people actually ask
“Retention configuration” is a label. “How long are logs retained?” is a question, and it matches the way the question will be asked. Question-shaped headings cost you nothing with human readers, who scan headings looking for their own question anyway.
One caveat worth stating plainly: write questions people ask, not questions you wish they asked. A page of invented FAQs is obvious to readers and useless for retrieval.
Repeat the subject instead of pronouns
Documentation is full of paragraphs that begin “It also supports…” or “This is configured in…”. Read alone, they refer to nothing. Naming the subject again (“The webhook endpoint also supports…”) reads as mildly repetitive in full and is unambiguous in isolation.
The same applies to units, versions and defaults. “Set it to 30” is not a fact; “Set retention_days to 30” is.
What helps and what hurts
| Practice | Effect |
|---|---|
| Server-rendered HTML | The content is available to every crawler and fetcher |
| Facts in tables with explicit units | Extracted accurately and quoted verbatim |
| One topic per page, complete | The whole answer lands in one retrieved chunk |
| Visible last-updated date and version | Assistants prefer sources they can date |
| Content injected by JavaScript | Frequently invisible; treat as unpublished |
| Answers split across many tiny pages | No single chunk contains the answer |
| Screenshots carrying the only instructions | Not read at all; put the steps in text |
| Marketing preamble before the answer | Pushes the answer out of the matched chunk |
Collapsed sections built on native <details> elements are in the HTML whether open or closed, so they are read normally. Tabbed interfaces vary: if every panel is rendered server-side and merely hidden with CSS, the content is present. If panels are fetched on click, it is not. Check by disabling JavaScript and reading the page.
Date and version everything
An assistant weighing two contradictory sources will favour the one it can date. A visible “Last updated” line and an explicit product version in the prose (“As of v4.2”) do more for citation accuracy than most technical SEO work.
It also protects you from the worse failure, which is not being ignored but being quoted correctly from a page that went stale two years ago.
Should you add an llms.txt file?
llms.txt is a proposed convention: a Markdown file at your domain root listing your key pages for language models. It costs an hour, and some tools do read it.
It is not a standard, and no major assistant guarantees it changes anything. Treat it as cheap insurance rather than a strategy: well-structured HTML is what actually gets cited, and a site that needs llms.txt to be legible has a structural problem the file will not fix.
Does any of this conflict with writing for people?
No, and that is the useful part. Every recommendation here (answer first, name the subject, question-shaped headings, facts in tables, real dates) is something a technical editor would have asked for in 2005. Retrieval systems are unusually literal readers, and writing that survives a literal reader is clearer for everyone.
The one genuine tension is repetition. Restating context in each section reads slightly redundantly to someone reading top to bottom. That is a small price, and most readers are not reading top to bottom anyway.
How do you know whether it is working?
- Ask the assistants directly. Put your ten most common support questions to a few of them and see whether you are cited, and whether the quote is accurate. This is crude and it is the most informative test available.
- Watch referrals from assistant domains in your analytics. Volumes are small but the trend is real.
- Check your logs for AI crawlers. If they are not fetching you, nothing else matters; start with
robots.txt. - Track support tickets that quote a wrong answer. An assistant confidently citing your stale page is a documentation bug with a new delivery mechanism.
Start with the top ten pages
Take your ten most-visited documentation pages. For each, move the answer to the top, turn the headings into questions, replace opening pronouns with their subjects, and put a date on the page. That is an afternoon, and it covers most of the traffic you have.