Overview
AI product docs have two readers: the human integrating the product and the LLM agent that reads the docs to call it. The second reader changes the rules: pages must be fetchable and parseable, model facts must be exact and dated, and limits must be written down. This page adds the AI-specific rules to technical-writing-standards; site-level mechanics are in write-llm-friendly-content.
Write for the agent as a first-class reader
Write atomic pages, one capability each, with answer-first openings an agent can quote (answer-first-content). Publish an agent-facing index at /llms.txt (llms-txt) and serve raw markdown next to rendered HTML so parsing is cheap.
Document the model surface exactly
Document model ids, context limits, rate limits, tool and function schemas, and the structured-output format. Integrators and agents both break on approximate values. State parameter restrictions per model, because they differ by model generation. An instruction file such as CLAUDE.md is this kind of doc; see claude-code-claude-md and llm-info-standard.
State limits, failure modes, and trust boundaries
Document what the product cannot do and how it fails: refusal behavior, the rate-limit response, timeouts, and known failure modes. For products that act on untrusted input, document the trust boundary so integrators build safely; see prompt-injection-defense.
Date every fact that moves
Model names, context windows, prices, and capabilities change on the provider’s schedule. Put a date or version on each such claim, and pair fast-moving pages with a changelog. An undated model claim is a future bug.
Give examples an agent can run unchanged
Provide complete request and response examples with auth, headers, payload, and expected output. Agents copy literally, so a partial snippet becomes a broken integration. Run the examples against the live API in CI.
Generate machine views from the human source
Build /llms.txt, schemas, and OpenAPI files from the same source as the human docs so they cannot diverge. Two hand-maintained copies drift; one generated source does not.
Avoid these failures
- Prose-only docs an agent cannot discover.
- Undated model facts.
- Documenting only the success path.
- Hand-maintained machine indexes.