Ship documentation your users' AI agents can actually act on.
Software now has two readers: the person deciding whether to use it, and the
agent that will install, configure, and call it on that person's behalf. The
AI Docs Standard is a simple, open convention for the second reader — a
single machine-first file, documentation.ai.md
, that an LLM or coding agent can load and use to run your product without guessing.
- 📄 The spec:SPEC.md - 🔥 The why:MANIFESTO.md - 🧩 A skeleton to copy:examples/TEMPLATE.md - 🌐 Canonical page:iwasoft.com/standards/ai-docs - 🤖 Live index (dogfood):iwasoft.com/llms.txt - 🧭 Sibling standard:AI Manifest Standard— presents asiteto AI (this presents aproduct) - 📜 License:CC BY 4.0— free to adopt with attribution
A human document earns trust by explaining why — the design, the tradeoffs, the story. An agent doesn't need to be persuaded; it needs the port number, the exact environment variable, the real response shape. Blend the two and you serve neither. So write two documents, for two readers, honestly. A fact an agent has to infer is a fact you failed to state.
Name |
documentation.ai.md (the .ai. infix marks the agent document) |
Format |
Markdown — structure an agent can parse, no decorative layout |
Language |
English only (LLMs are English-first); one file, not a matrix |
Scope |
one file per product, per released version, beside the human docs |
ai
is a reader, not a spoken language — it never goes in your site's language switcher.
Add next to your product's docs, following thedocumentation.ai.md
required sections: identity → install → configuration → interface quickstart → admin surface → architecture facts → links.Keep it correct per release— every version ships its own, verified against the real product.** Make it discoverable**— link it from your site'sllms.txt
, and add the badge below.
[](https://github.com/iwasoftcom/ai-docs-standard)
The document must be self-sufficient: an agent that has read only this file can install, call, and configure the product — no human docs, no source repo, no guessing. Dense over prose; tables over paragraphs; every command copy-pasteable and verified; absolute honesty about status. Full requirements in SPEC.md.
Complementary, not competing. llms.txt is a site-root
index of a website's content;
documentation.ai.md
is a per-product, per-release operational manual(closer to
llms-full.txt
). A site's
llms.txt
can link to each product's documentation.ai.md
. Adopt either
independently.Every iwasoft product ships a documentation.ai.md
with each release — real, published examples of the standard in practice.
See a real documentation.ai.md:
More:
Canonical write-up:iwasoft.com/standards/ai-docs** Live index of every product's AI doc:iwasoft.com/llms.txt- Or browse the products on iwasoft.com— each product's Documentation panel includes anAI / LLM** entry.
The standard evolves in the open — see CONTRIBUTING.md. Open an issue to discuss a change; send a PR to propose one.
The AI Docs Standard is authored and stewarded by ** iwasoft** and released under
CC BY 4.0: adopt it, adapt it, build on it — just keep the attribution. Canonical write-up:
iwasoft.com/standards/ai-docs.