Overview
Documentation for AI software products has two readers at once: the human integrating the product and the LLM agent that will read the docs to use it. That dual audience changes the rules: docs need machine-readable structure, dated model facts, honest capability limits, and copy-paste-ready examples an agent can lift. This page extends the general standards in technical-writing-standards with the AI-specific practices; for the site-level mechanics see write-llm-friendly-content.
Write for the agent as a first-class reader
Assume an LLM will fetch and act on the docs. Prefer atomic pages, one capability each, with answer-first openings the agent can quote (see answer-first-content). Ship a machine-readable index so an agent can discover every page; /llms.txt is the agent-facing sitemap (see llms-txt). Provide raw-markdown URLs alongside rendered HTML so parsing is cheap.
Document the model surface explicitly
AI products expose model-shaped surfaces: prompts, tools, token limits, and response schemas. Document each precisely: model ids, context limits, rate limits, the exact tool and function schemas, and the structured-output format. Agents and integrators both depend on these being exact, not approximate. A CLAUDE.md-style instruction file is itself this kind of doc; see claude-code-claude-md and llm-info-standard.
State limits, failure modes, and safety boundaries
Document what the product cannot do and how it fails, not just the happy path. Name the refusal behavior, the rate-limit response, the timeout, and the known failure modes. For products that act on untrusted input, document the trust boundary and the injection-defense posture so integrators build safely; see prompt-injection-defense.
Date everything that moves
Model names, context windows, pricing, and capabilities change on a provider’s schedule, not yours. Date pages and version examples so a reader knows whether a fact is current. An undated claim about a model is a future bug. Pair fast-moving pages with a changelog.
Give examples an agent can run unchanged
Provide complete, runnable request and response examples, including auth, headers, and the full payload, with expected output. An agent copies examples literally; a partial snippet becomes a broken integration. Test the examples in CI against the live API so they cannot drift.
Keep human and machine views in sync from one source
Generate the machine-readable artifacts (/llms.txt, schemas, OpenAPI) from the same source as the human docs at build time, so they cannot diverge. Two hand-maintained copies drift; one generated source does not. Follow the structure and voice rules in editorial-style.
Pitfalls
- Prose-only docs an agent cannot parse or discover.
- Undated model facts that silently go stale.
- Documenting only success, leaving failure and limits undocumented.
- Hand-maintained machine indexes that drift from the human docs.