# 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. Source: https://armature.tech/library/audit-your-docs-for-coding-agents Published: 2026-09-03 Publisher: Armature, Inc. (https://armature.tech) --- 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? ```bash curl -s https://yourdocs.example.com/quickstart | head -c 2000 ``` If 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? ```bash curl -s https://yourdocs.example.com/robots.txt ``` Look 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? ```bash curl -s https://yourdocs.example.com/quickstart.md | head -c 500 ``` Agents 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: ```html ``` ### 4. Does `llms.txt` exist? ```bash curl -s https://yourdocs.example.com/llms.txt ``` About one site in ten has one. It costs an hour. See the [llms.txt guide](/library/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](/library/structured-data-for-developer-tools). ### 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](/library/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-queue ``` ### 14. 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 documentation ``` ### 17. 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. ## Read next - [Documentation for coding agents](https://armature.tech/library/documentation-for-coding-agents) (Markdown: https://armature.tech/library/documentation-for-coding-agents.md) - [How to write a quickstart an agent can follow](https://armature.tech/library/write-a-quickstart-an-agent-can-follow) (Markdown: https://armature.tech/library/write-a-quickstart-an-agent-can-follow.md) - [llms.txt: what it is, what it does, and what to put in it](https://armature.tech/library/llms-txt-guide) (Markdown: https://armature.tech/library/llms-txt-guide.md) - [Package naming for coding agents](https://armature.tech/library/package-naming-for-coding-agents) (Markdown: https://armature.tech/library/package-naming-for-coding-agents.md) - [Agent readiness](https://armature.tech/library/agent-readiness) (Markdown: https://armature.tech/library/agent-readiness.md) - [robots.txt for AI crawlers](https://armature.tech/library/robots-txt-for-ai-crawlers) (Markdown: https://armature.tech/library/robots-txt-for-ai-crawlers.md) --- Armature helps software products get discovered and used by coding agents. Service: https://armature.tech/discoverability · Results: https://armature.tech/leaderboards/sectors · Contact: contact@armature.tech