Developer documentation is found through search, through AI coding assistants and through AI chat tools that developers ask for help, so it needs to be public, server-rendered, organised by task, stable in its URLs across versions, and easy for both people and machines to read. The highest-value pages are often those that answer a specific problem, such as an error message, an integration step or a migration, because that is exactly what developers type and ask. Good documentation is also one of the strongest trust signals a developer-facing product has.
How developers find documentation
- Searching an error message, method name or “how to [task] with [product]”
- Asking AI chat tools and coding assistants, which often fetch or have learned from public docs
- Following links from GitHub, Stack Overflow and community posts
Structure
| Section | Purpose |
|---|---|
| Quickstart | From zero to a working result in minutes |
| Guides by task | “Authenticate with OAuth”, “Send a webhook”, “Paginate results” |
| API reference | Generated from the specification, one page or anchor per endpoint |
| Errors | One section per error code or message, with causes and fixes |
| SDKs and examples | Language-specific setup and working code |
| Changelog and migration guides | What changed, with dates, and how to upgrade |
Error pages are underrated
Developers copy error messages straight into search engines and AI tools. A page that shows the exact error text, explains the cause in the first sentence and gives the fix is one of the most-used pages a product can have. Use the error text as the heading.
Technical requirements
- Server-rendered or statically generated pages; many documentation tools produce static HTML, which is ideal.
- Code in real text blocks, not images, with a language label.
- Stable URLs: when a version changes, keep the same path for the latest version and put older versions under versioned paths.
- Canonical tags pointing older version pages to the latest equivalent where the content is the same, or noindex old versions that are no longer supported.
- Site search that handles method names and error codes exactly.
- A sitemap for the documentation, and links between the docs and the main site.
For AI coding assistants
- Keep explanations next to code, so a passage is useful on its own.
- Publish an llms.txt file listing key documentation pages, and Markdown versions of pages, which some AI coding tools use. See adding llms.txt and Markdown versions.
- Mark deprecated methods clearly, so assistants do not recommend them.
Measure
- Search Console queries that land on docs, especially error messages
- Internal search terms with no results, which show missing pages
- Support tickets that documentation should have answered; see using support data
Frequently asked questions
Should documentation be behind a login?
Keep it public where possible. Gated docs cannot be found in search or read by AI tools, and they make evaluation harder for prospective users.
Subdomain or subfolder?
Either works if it is crawlable and linked from the main site. A subfolder keeps signals on one host.
How do we stop old versions ranking above the current one?
Canonical old pages to the latest equivalent, add a clear banner linking to the current version, and link internally only to current pages.
Sources
- Google Search Central, “Consolidate duplicate URLs”
- llmstxt.org, the llms.txt proposal