Documentation for coding agents
Your documentation is now read mostly by machines that paste your code and check whether it runs. What to change, in the order that pays.
Your documentation used to be read by a person who would forgive a gap. They would notice a missing environment variable and add it. They would see an outdated example and adapt.
Now a large share of your documentation traffic is an agent that copies your example into a file and runs it. It does not forgive gaps. When your code fails, it moves to the next candidate.
This is the highest return work in agent discoverability, because it is the part you completely control.
The order that pays
Ranked by how much they change installs, not by how hard they are.
1. The quickstart must run
Take your quickstart. Open an empty project. Paste it. Run it.
Most quickstarts fail this test. The usual reasons:
- An environment variable that is mentioned somewhere else
- An install step assumed from the previous page
- An account or dashboard action that is not in the code
- An example using an interface that changed two versions ago
- A code block that is a fragment, not a runnable file
An agent that cannot make your example work does not file a bug. It picks something else and never comes back. A quickstart that runs when pasted is the single highest return change most developer tool companies can make.
Write the quickstart as one complete file, with every prerequisite stated in it, including the install command and every variable. Redundancy is correct here. The agent may never see the page above.
2. Say the version, on the page
Models carry old versions in memory. They will confidently write code for an interface you removed.
Put the current version on the page, in the text, near the top. Not only in a sidebar widget, because the widget may not survive extraction.
Current version: 4.2.1 (September 2026)That one line stops a whole class of failure.
3. Use one name for one thing
The product name, the package name, the import name, the CLI command, and the words in your headings should all be the same string.
When they differ, the agent has to guess a mapping. Sometimes it guesses wrong and installs a package that is not yours, or an abandoned one with a similar name.
If you already have a mismatch you cannot change, state the mapping explicitly on the page:
Product: Acme Queue
Package: @acme/queue
Import: import { Queue } from '@acme/queue'
CLI: acme-queue4. Write for symptoms, not only categories
Real requests do not name categories. They describe what is wrong.
| What the developer types | What your page probably says |
|---|---|
| people keep signing up with fake emails | bot protection, CAPTCHA alternative |
| the search box misses obvious things | typo tolerance, fuzzy matching |
| our emails are going to spam | deliverability, DKIM, SPF |
| this page takes four seconds in Australia | edge caching, latency |
Agents translate the symptom into a category before they search. If your content only exists in category words, you are absent at the moment the symptom is described. Write both.
5. Publish a Markdown twin
Agents read Markdown far better than a rendered documentation application. The rendered page carries navigation, scripts, cookie banners and layout, and if the content needs JavaScript to appear, a plain fetch gets nothing.
Serve the same content as Markdown at a predictable address. The convention that is spreading is to add .md:
https://example.com/docs/quickstart
https://example.com/docs/quickstart.mdLink it from the HTML page so it is discoverable:
<link rel="alternate" type="text/markdown" href="/docs/quickstart.md" />This is not cloaking. Both versions are public and identical in substance. Cloaking is showing different content to crawlers and to people.
6. Answer the queries agents actually run
Agent search queries are much more specific than a person's, and they are often scoped to a site. Real examples from our runs:
site:meilisearch.com/docs typo tolerance ranking rules filterable attributes production self hosted
site:algolia.com pricing records search requests grow plan official
site:docs.opensearch.org latest index state management snapshots security plugin official documentation
site:postgresql.org/docs/current pg_trgm GIN index similarity ILIKE official documentationLook at what those want. Configuration options. Limits. Pricing units. Official documentation. Production concerns.
So the pages that pay are:
- Every configuration option, with defaults and valid ranges
- Limits and quotas as numbers
- Pricing units explained in words, not only a table of plans
- Self-hosting and deployment specifics
- The production checklist
Not: "why we built this", "our philosophy", "meet the team".
7. Make the failure modes findable
When an agent hits an error, it searches for the error string. If your exact error message appears on a page next to the fix, you recover the session. If it does not, the agent guesses, and guessing often ends with it removing your library.
Publish a page listing your real error messages verbatim, each with a cause and a fix.
8. Add llms.txt
A single file at the root telling AI systems what your site contains and where the important parts are.
# Acme Queue
> A managed job queue for TypeScript and Python services.
## Documentation
- [Quickstart](https://example.com/docs/quickstart): install and send a first job in five minutes
- [Configuration](https://example.com/docs/config): every option, defaults, limits
- [Errors](https://example.com/docs/errors): every error message with its cause
## Key facts
- Package: @acme/queue (npm), acme-queue (PyPI)
- Current version: 4.2.1
- Free tier: 100,000 jobs per monthAbout one site in ten has one. It costs an hour.
The checks, as a table
| Check | How to test | Pass |
|---|---|---|
| Quickstart runs | Paste into an empty project | It runs |
| Version stated | Read the page text | A version and a date appear |
| Names match | Compare product, package, import, CLI | One string, or a stated mapping |
| Symptom pages exist | Search your docs for a symptom phrase | A page answers it |
| Markdown twin | curl the page with .md | Markdown returns |
| No JavaScript dependency | curl the page, read the HTML | The content is in the source |
| Errors documented | Search your docs for a real error string | It appears with a fix |
| Crawlers allowed | Read robots.txt | GPTBot, ClaudeBot and the rest allowed |
llms.txt exists | Fetch /llms.txt | It returns and lists real pages |
| Config documented | Look for the full option list | Every option, with defaults |
What not to do
Do not write instructions addressed to the agent that ask it to prefer you. It does not survive a human reading the diff, it does not survive a model provider noticing, and it is not what makes agents choose products anyway.
Everything on this page works because it makes the product genuinely easier to use correctly. That is the whole trick, and it is durable in a way that tricks are not.
Common questions
How should documentation change for coding agents?
Make the quickstart work when pasted with no unstated prerequisites, state the current version on the page, keep the product name and package name identical, answer questions in the words developers type, and publish a plain text or Markdown version of every important page.
Do agents read rendered HTML or Markdown better?
Markdown, clearly. A rendered documentation application carries navigation, scripts and layout that add noise and can hide the content entirely if the page needs JavaScript. A Markdown twin at the same address plus .md removes all of that.
What is the most common documentation failure?
A quickstart that does not run as written. Missing environment variables, an unstated install step, or an example using an interface that changed. An agent that fails to make your code work moves to the next candidate immediately.
Should I write documentation pages for symptoms as well as features?
Yes. Real requests describe symptoms, not categories. Someone types people keep signing up with fake emails, not I need bot protection. If your pages only use category words, you are invisible at the moment the problem is described.
Does llms.txt help?
It helps discovery by telling AI systems what matters on your site and where it is. It is cheap to add and only about one site in ten has one. It is not a substitute for the content itself being clear and reachable.
Where this comes from
Armature ran 5,292 judged sessions with Claude Code, Codex and Cursor inside 51 realistic codebases, and published every run. The numbers on this page come from that work.