Check this page with an assistantOpens a chat asking it to summarise this article and name the evidence behind each claim.
Claude opens with the prompt on your clipboard: Anthropic does not support prefilled prompts on the web, and we would rather copy it than ship a button that drops it.
Nobody Browses Documentation
A developer with a problem searches the problem. They paste an error message, or describe what they are trying to do, and open whatever answers it. Your carefully structured navigation is used by people who already know your product; everyone else arrives sideways on a specific page.
That has a consequence teams underestimate: every documentation page is a landing page. It has to establish what product this is, what version, and what problem it solves, because the reader has no context from anything before it. Docs written as chapters in a book fail this, and the failure is invisible internally because everyone testing them started at the beginning.
It is also a competitive surface rather than a support cost. When someone searches how to accomplish something, the page that answers it well shapes which tool they use. Documentation that ranks for the problem rather than the product name acquires developers who were not looking for you.
The New Reader Is a Coding Assistant
Assistants embedded in editors fetch documentation at request time to answer questions about your product. The developer asks how to do something, the assistant retrieves your docs, and an answer appears without anyone visiting your site.
This is a genuine shift in who documentation serves. The reader is a machine summarising for a developer, which puts weight on exactly the properties good documentation already needed: accuracy, currency, and pages that make sense in isolation. It also raises the cost of being wrong, because an incorrect code sample gets executed rather than read sceptically.
It is also the one context where the llms.txt proposal has a real argument. Our general position is that it lacks a committed consumer and should never be paid for, set out in our review of the file. Docs sites are the exception acknowledged there: a curated index of the pages that matter genuinely helps a tool fetching your documentation, and it costs an afternoon. Cheap insurance, not a visibility tactic.
Versioning Is the Failure Nobody Plans
Unversioned URLs whose content silently changes as the product evolves produce the worst outcome available: a page that was correct when indexed and is wrong when read. Version handling is the single highest-value structural decision on a docs site.
| Decision | Poor version | Version that works |
|---|---|---|
| Version in URL | None, so old answers become wrong silently | Versioned paths with the current one canonical |
| Old versions | Deleted, breaking every reference | Kept, marked superseded, linked to current |
| Version visibility | In a dropdown nobody notices | Stated on the page, in the text |
| Deprecated features | Page removed, so searchers hit nothing | Marked deprecated with the replacement named |
| Code samples | In images, or untested against the current release | Real text, tested, with the version stated |
The code sample row deserves emphasis now that assistants are reading these pages. A sample in a screenshot is unreadable to everything you were trying to reach, and an untested sample propagates into codebases through an assistant that had no way to verify it. Samples in real text, tested against the version they claim, is the baseline.
Structuring Pages as Answers
The same extractability discipline that serves generated answers serves developers scanning for the one thing they need: a heading naming the task, a direct answer under it, and sections that stand alone.
Title pages by the task rather than the feature. "How to authenticate a request" is searched; "Authentication module" is not. Include the error messages your product actually emits, verbatim, in the pages that explain them, because pasting an error into a search box is the single most common way developers arrive anywhere.
Then make each page self-contained enough to be lifted out. No references to the previous chapter, no unresolved pronouns, and enough context that a reader arriving cold knows what they are looking at. That is the passage-level property described in query fan-out, and documentation happens to be the content type where it matters most.
Where the Search Value Actually Sits
The pages worth deliberate attention are not the API reference. They are the problem-shaped pages: error explanations, integration guides for named tools, migration guides, and comparisons against the alternative approach.
Error pages acquire developers who have never heard of you, because someone else's error message led them to your explanation. Integration guides catch people who have already chosen a stack and are looking for what connects to it, which is high-intent in a way general documentation is not, and it overlaps the integration-page argument in B2B SaaS SEO.
Reference documentation, by contrast, is used by people who already have you. It needs to be complete and accurate and it is not an acquisition surface, which is worth knowing before someone proposes an SEO programme aimed at your endpoint list. The distinction is the same intent question covered in search intent, applied to a content type where it is rarely asked.
Questions Teams Ask About Documentation SEO
- Why does documentation need SEO at all?
Because developers search for solutions rather than browsing your docs site. Someone hitting an error message searches the error, not your navigation, and the page that answers it wins the developer regardless of whose product they were using. Documentation that only works if you already know where to look is documentation that only serves existing users.
- Do AI coding assistants really read my docs?
Yes, and this is the newest reason to care. Assistants integrated into editors fetch documentation at request time to answer questions about your product. That means your docs are increasingly consumed by a machine summarising them for a developer who never visits, which puts a premium on pages that are accurate, current, and readable without surrounding context.
- Is llms.txt worth it for documentation sites?
Documentation sites are the one context where llms.txt is arguable rather than purely speculative, because assistants fetching docs benefit from a curated index. It remains an unadopted proposal with no committed major consumer, so treat it as cheap insurance rather than a visibility tactic, and never pay for it.
- How should I handle documentation for multiple versions?
Give each version a stable URL, mark the current version canonical, and make the version obvious on the page itself. The common failure is unversioned URLs that silently change meaning as the product evolves, which produces answers that were correct when indexed and are wrong when read.
- Should docs live on a subdomain or a subfolder?
A subfolder consolidates everything on one domain, which is generally preferable. That said, docs platforms frequently impose a subdomain and the practical cost is modest for this content type, since developers arrive through search on specific problems rather than through your marketing site. It is not worth a painful migration on its own.
