Audit your documentation for coding agents
Twenty checks, each one testable in minutes, ordered by how much they change installs. Run this before you spend anything on content.
This is the cheapest work in agent discoverability and it is almost always the highest return. Every check below can be done in minutes with curl, a browser and an empty project.
Work down the list. It is ordered by effect on installs, not by effort.
The reachability checks
If an agent cannot read the page, nothing else on this list matters.
1. Is the content in the HTML source?
curl -s https://yourdocs.example.com/quickstart | head -c 2000If you see your content, good. If you see an empty application shell, an agent that does not execute JavaScript sees nothing.
Fix: server render, pre-render, or serve a static copy.
2. Are AI crawlers allowed?
curl -s https://yourdocs.example.com/robots.txtLook for explicit rules for GPTBot, ChatGPT-User, OAI-SearchBot, ClaudeBot, PerplexityBot, Google-Extended, Applebot-Extended, CCBot. A blanket Allow: / covers them, but naming them is clearer and survives a future edit that adds a blanket deny.
3. Is there a Markdown version?
curl -s https://yourdocs.example.com/quickstart.md | head -c 500Agents read Markdown far better than a rendered documentation site. A twin at the same address plus .md is a small change with a real effect, and almost nobody does it.
Link it from the page so it is discoverable:
<link rel="alternate" type="text/markdown" href="/quickstart.md" />4. Does llms.txt exist?
curl -s https://yourdocs.example.com/llms.txtAbout one site in ten has one. It costs an hour. See the llms.txt guide.
5. Does anything important sit behind a login or a form?
An agent cannot fill in a form. Gated content is invisible to the buyer.
The correctness checks
5b. Is the structured data honest?
Every page should carry markup describing what a reader can actually see on it. Marking up an FAQ that is not on the page is a guidelines violation that can cost a whole site its rich results. See structured data for a developer tool site.
6. Does the quickstart run when pasted?
Open an empty project. Paste it. Run it. Use nothing you know about the product.
Most quickstarts fail. This is the single most valuable fix on the page. See how to write a quickstart an agent can follow.
7. Is the install command in the same block as the code?
Not on the previous page. In the same block, every time.
8. Is every environment variable named where it is used?
With a comment saying where it comes from.
9. Are the steps that happen outside the code written down?
Creating an account, creating a project, copying a key. Put them in the code block as numbered comments, in sequence.
10. Is the code a complete file or a fragment?
A three-line fragment with no imports cannot be run. Make it complete. Longer is fine.
11. Is the current version stated on the page, in the text?
Current version: 4.2.1 (September 2026)Not only in a sidebar widget. In the text, near the top, where extraction will find it.
12. Do the examples still work against the current release?
Put them in continuous integration: extract each code block, run it, fail the build when it breaks. Examples rot silently otherwise.
The naming checks
13. Do the product name, package name, import name and CLI command match?
If they cannot, write the mapping down on the page:
Product: Acme Queue
Package: @acme/queue
Import: import { Queue } from '@acme/queue'
CLI: acme-queue14. Is there a similarly named package that is not yours?
Search your package registry for near misses. If one exists, say so explicitly on the install page, because an agent guessing a package name may find it instead.
15. Do your headings use the same words as your product name?
An agent matching a query to a page uses the heading. Consistency is worth more than variety here.
The coverage checks
16. Is there a complete configuration reference?
Every option, its default, its valid range, and what happens when it is wrong. One place, not scattered through tutorials.
Agents search for this constantly. Real queries from our sessions:
site:example.com/docs typo tolerance ranking rules filterable attributes production self hosted
site:example.com/docs index state management snapshots security plugin official documentation17. Are limits and quotas published as numbers?
Rate limits, size limits, retention, concurrency. In a table, on a page that says "limits".
18. Is pricing explained in units?
Not plan names. What a unit is, what counts as one, where the meter ticks. Agents ask, because some of the people asking them have cost constraints.
19. Are your error messages published verbatim?
One page, every error string, with the cause and the fix. When an agent hits an error it searches for the exact text. Own that result and you recover the session.
20. Are there pages written in symptom language?
Real requests describe symptoms, not categories.
| Users type | Most docs say |
|---|---|
| people keep signing up with fake emails | bot protection |
| the search box misses obvious things | typo tolerance |
| our emails are going to spam | deliverability |
If your pages only exist in category words, you are absent at the moment the symptom is described. Write both.
The scorecard
| # | Check | Pass |
|---|---|---|
| 1 | Content in HTML source | |
| 2 | AI crawlers allowed by name | |
| 3 | Markdown twin exists | |
| 4 | llms.txt exists | |
| 5 | Nothing important gated | |
| 6 | Quickstart runs when pasted | |
| 7 | Install command in the same block | |
| 8 | Every variable named where used | |
| 9 | Out-of-code steps written down | |
| 10 | Examples are complete files | |
| 11 | Current version in the page text | |
| 12 | Examples tested in CI | |
| 13 | Names match across product, package, import, CLI | |
| 14 | Near-miss package names addressed | |
| 15 | Headings use the product's own words | |
| 16 | Complete configuration reference | |
| 17 | Limits published as numbers | |
| 18 | Pricing explained in units | |
| 19 | Error messages published verbatim | |
| 20 | Symptom-language pages exist |
Most teams pass fewer than half on the first run. The first six are worth more than the other fourteen combined.
The check this list cannot do
None of the above tells you where sessions actually stall. For that you have to run an agent.
Take a repository that looks like your users' projects, give an agent a one-line request your product answers, and watch. Do it five times, because the same agent on the same repository disagrees with itself about a quarter of the time.
The step where it hesitates is your real bug, and it is often not on this list.
Common questions
How do I audit my documentation for coding agents?
Run the twenty checks on this page. The important ones are whether the quickstart runs when pasted, whether the current version is stated on the page, whether your product name and package name match, whether the content is in the HTML source rather than injected by JavaScript, and whether a Markdown version exists.
What is the single most valuable fix?
Making the quickstart run when pasted into an empty project with no unstated prerequisites. It is the last step of every session you nearly won, and most quickstarts fail it.
How do I know if an agent can even read my docs?
Fetch a page with curl and read what comes back. If the content is not in the response, an agent that does not execute JavaScript sees an empty page.
Does the audit need any tools?
No. Every check on this page can be done with curl, a browser and an empty project. The optional extra is running a coding agent against a test repository, which is the only way to see where sessions actually stall.
How often should I re-run it?
After any documentation platform change, any major release, and otherwise every quarter. Examples rot quietly and a version number goes stale the day you ship.
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.