---
title: "Documentation best practices for AI software products"
slug: "documentation-for-ai-products"
category: "writing"
tags: ["writing", "documentation", "ai", "llms-txt", "best-practices"]
status: "stable"
last_updated: 2026-06-07
summary: "How to document AI products for two audiences at once: humans and the LLM agents that read the docs, with machine-readable structure, honest limits, and dated model facts."
description: "Documentation for AI products: write for humans and agents, ship machine-readable structure and llms.txt, state limits, and date model facts."
aliases: ["documenting AI products", "AI product documentation", "docs for LLM products", "writing docs for AI software"]
related: ["[[writing/technical-writing-standards]]", "[[howto/write-llm-friendly-content]]", "[[seo/llms-txt]]", "[[seo/answer-first-content]]", "[[meta/llm-info-standard]]", "[[ai-agents/claude-code-claude-md]]", "[[ai-agents/prompt-injection-defense]]", "[[writing/editorial-style]]"]
---

## 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 [[writing/technical-writing-standards]] with the AI-specific practices; for the site-level mechanics see [[howto/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 [[seo/answer-first-content]]). Ship a machine-readable index so an agent can discover every page; `/llms.txt` is the agent-facing sitemap (see [[seo/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 [[ai-agents/claude-code-claude-md]] and [[meta/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 [[ai-agents/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 [[writing/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.

## Related

- [[writing/technical-writing-standards]]
- [[howto/write-llm-friendly-content]]
- [[seo/llms-txt]]
- [[seo/answer-first-content]]
- [[meta/llm-info-standard]]
- [[ai-agents/claude-code-claude-md]]
- [[ai-agents/prompt-injection-defense]]