Show HN: Documentation.ai.md – a docs standard for AI agents, not humans

Software company iwasoft has released the AI Docs Standard, an open convention for a machine-first documentation file named documentation.ai.md that AI agents can use to install, configure, and call a product without human intervention. The standard, licensed under CC BY 4.0, specifies a single Markdown file per product per released version with required sections in a fixed order, and iwasoft ships such a file with every product release as a real-world example.

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 /iwasoftcom/ai-docs-standard/blob/main/SPEC.md - 🔥 The why: MANIFESTO.md /iwasoftcom/ai-docs-standard/blob/main/MANIFESTO.md - 🧩 A skeleton to copy: examples/TEMPLATE.md /iwasoftcom/ai-docs-standard/blob/main/examples/TEMPLATE.md - 🌐 Canonical page: iwasoft.com/standards/ai-docs https://iwasoft.com/standards/ai-docs - 🤖 Live index dogfood : iwasoft.com/llms.txt https://iwasoft.com/llms.txt - 🧭 Sibling standard: AI Manifest Standard https://github.com/iwasoftcom/ai-manifest-standard — presents a site to AI this presents a product - 📜 License: CC BY 4.0 /iwasoftcom/ai-docs-standard/blob/main/LICENSE — 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 the documentation.ai.md required sections /iwasoftcom/ai-docs-standard/blob/main/SPEC.md required-sections-in-this-order : 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's llms.txt , and add the badge below. AI Docs Standard https://img.shields.io/badge/docs-AI%20Docs%20Standard-5850ec 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 /iwasoftcom/ai-docs-standard/blob/main/SPEC.md . Complementary, not competing. llms.txt https://llmstxt.org 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 https://iwasoft.com 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 https://iwasoft.com/standards/ai-docs Live index of every product's AI doc: iwasoft.com/llms.txt https://iwasoft.com/llms.txt - Or browse the products on iwasoft.com https://iwasoft.com — each product's Documentation panel includes an AI / LLM entry. The standard evolves in the open — see CONTRIBUTING.md /iwasoftcom/ai-docs-standard/blob/main/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 /iwasoftcom/ai-docs-standard/blob/main/LICENSE : adopt it, adapt it, build on it — just keep the attribution. Canonical write-up: iwasoft.com/standards/ai-docs https://iwasoft.com/standards/ai-docs .