How to Make Your Docs Readable by AI Assistants

The result is documentation that reads correctly when one section of it is quoted on its own by a system you cannot inspect. Set expectations first: how any given assistant selects, ranks and reproduces source material is unpublished, differs between providers, and changes without announcement. Everything below is either a change worth making for the human who lands mid-page, or an access decision the providers do document.

Before you start

Fetch one of your own documentation pages with curl and read what comes back. If the body text is not in that response, no crawler that skips JavaScript execution can see your documentation, and nothing else in this guide matters until that is fixed.

Have a position ready on crawler access. Allowing a training crawler and allowing a live fetch made while a user waits for an answer are separate decisions, controlled by separate user agents, with different consequences.

Steps

1. Serve the text in the initial HTML response.
   Server-rendered or statically generated pages are readable by everything. A client-rendered documentation app may be read by some fetchers and not others, and you will never get a clear report about which.

2. Set your robots.txt policy deliberately, agent by agent.
   Providers publish their crawler names - GPTBot, ClaudeBot, PerplexityBot, Google-Extended among them - and each documents which of its activities the agent covers. Blocking everything by default is a choice with a consequence: assistants then answer questions about your product from third-party pages you do not control.

3. Write each ## section so it stands alone.
   Most readers of a help article arrive mid-page, from a search result or a deep link, and read one section. A section beginning "Once you have done that, click Continue" is meaningless to them. Name the feature and the context in the section itself, even when it reads slightly redundantly to someone reading top to bottom.

4. Put the answer before the explanation.
   State what to do, then why. A reader skimming for the instruction scrolls past background, and a section that opens with three sentences of context is one they abandon before reaching the answer.

5. Name the product and the version in the body text.
   Deep links, reader-mode browsers and copied excerpts strip your header, footer and breadcrumbs. If the only place your product name appears is the page chrome, a quoted passage cannot be attributed. Use nouns rather than pronouns in the first sentence of each section for the same reason: "The webhook retries three times" survives being quoted, "It retries three times" does not.

6. Use real structural HTML.
   Headings in order, lists marked up as lists, tables as tables, code in <pre><code>. Text rendered inside a screenshot is invisible to every reader in this guide, human and otherwise, which is an accessibility argument before it is anything else.

7. Keep one canonical page per topic.
   Three near-identical articles about the same feature split whatever ranking signal exists and leave any reader, or assistant, with three partial answers instead of one complete one. Consolidate and redirect.

8. State facts explicitly rather than by implication.
   "The free plan includes three projects" can be quoted. A pricing table with the number in an unlabelled column, or a sentence saying "as above", cannot.

9. Publish dates and keep them accurate.
   A visible last-updated date in the text gives any reader a way to judge staleness, and gives you a way to spot pages that have quietly aged past usefulness.

A section that names its own subject reads correctly wherever it is quoted. One beginning 'once you have done the above' arrives useless.

Common mistakes

Optimising for a ranking behaviour nobody has published. Providers document crawler names and access controls, not selection logic. Google's May 2026 guide to optimising for generative AI features is explicit that no chunking, no special rewriting for AI, no llms.txt and no schema markup are needed to appear in its AI features. Advice claiming to know how a model chooses passages is inference presented as fact, including advice that agrees with this guide.

Writing "AI-optimised" filler. Padding pages with question-shaped headings and restated keywords produces worse documentation for humans in exchange for a benefit no provider has confirmed exists.

Blocking every AI crawler and then auditing what assistants say. If your pages are unreadable, the answers get built from forum posts, competitor comparisons and old release notes instead. That is a legitimate trade to make deliberately and a poor one to make by default.

Hiding content in tabs and accordions. Google indexes collapsed content, but a reader's in-page search does not see it, and text that only appears after a click is the first thing lost when a page is quoted, printed or read aloud.

Leaving the good material behind a login. Documentation gated behind authentication cannot be read by anything, so the public answer about your product ends up assembled from whatever is outside the gate.

When this stops scaling

Section-level self-containment is a per-article discipline, and it decays the way every writing convention decays: it holds while one person writes everything, and starts drifting the moment three people do. Somewhere past forty or fifty articles maintained by a rotating cast, you will have a mix of pages that read well as fragments and pages that depend entirely on their surroundings, with no way to tell which is which short of reading all of them.

The structural fix is to make the shape a property of how pages are produced rather than a rule people follow - a template that forces the context into each section, applied at generation time. That is how SupportPages builds its output, along with the sitemap that goes with it and an llms.txt for the assistants that read one - Google Search does not. The caveat belongs here rather than in a footnote: consistent structure makes documentation easier to quote correctly, and no structural choice makes an assistant say what you want. The only lever with a reliable effect is whether the accurate source exists and can be read at all.