{"slug": "show-hn-documentation-ai-md-a-docs-standard-for-ai-agents-not-humans", "title": "Show HN: Documentation.ai.md – a docs standard for AI agents, not humans", "summary": "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.", "body_md": "**Ship documentation your users' AI agents can actually act on.**\n\nSoftware now has two readers: the person deciding whether to use it, and the\nagent that will install, configure, and call it on that person's behalf. The\n**AI Docs Standard** is a simple, open convention for the second reader — a\nsingle machine-first file, `documentation.ai.md`\n\n, that an LLM or coding agent\ncan load and use to run your product without guessing.\n\n- 📄\n**The spec:**[SPEC.md](/iwasoftcom/ai-docs-standard/blob/main/SPEC.md) - 🔥\n**The why:**[MANIFESTO.md](/iwasoftcom/ai-docs-standard/blob/main/MANIFESTO.md) - 🧩\n**A skeleton to copy:**[examples/TEMPLATE.md](/iwasoftcom/ai-docs-standard/blob/main/examples/TEMPLATE.md) - 🌐\n**Canonical page:**[iwasoft.com/standards/ai-docs](https://iwasoft.com/standards/ai-docs) - 🤖\n**Live index (dogfood):**[iwasoft.com/llms.txt](https://iwasoft.com/llms.txt) - 🧭\n**Sibling standard:**[AI Manifest Standard](https://github.com/iwasoftcom/ai-manifest-standard)— presents a*site*to AI (this presents a*product*) - 📜\n**License:**[CC BY 4.0](/iwasoftcom/ai-docs-standard/blob/main/LICENSE)— free to adopt with attribution\n\nA human document earns trust by explaining *why* — the design, the tradeoffs,\nthe story. An agent doesn't need to be persuaded; it needs the port number, the\nexact environment variable, the real response shape. Blend the two and you serve\nneither. So write two documents, for two readers, honestly. **A fact an agent\nhas to infer is a fact you failed to state.**\n\nName |\n`documentation.ai.md` (the `.ai.` infix marks the agent document) |\nFormat |\nMarkdown — structure an agent can parse, no decorative layout |\nLanguage |\nEnglish only (LLMs are English-first); one file, not a matrix |\nScope |\none file per product, per released version, beside the human docs |\n\n`ai`\n\nis a **reader**, not a spoken language — it never goes in your site's\nlanguage switcher.\n\n**Add** next to your product's docs, following the`documentation.ai.md`\n\n[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`\n\n, and add the badge below.\n\n```\n[![AI Docs Standard](https://img.shields.io/badge/docs-AI%20Docs%20Standard-5850ec)](https://github.com/iwasoftcom/ai-docs-standard)\n```\n\nThe document must be **self-sufficient**: an agent that has read only this file\ncan install, call, and configure the product — no human docs, no source repo, no\nguessing. Dense over prose; tables over paragraphs; every command copy-pasteable\nand verified; absolute honesty about status. Full requirements in\n[SPEC.md](/iwasoftcom/ai-docs-standard/blob/main/SPEC.md).\n\nComplementary, not competing. [ llms.txt](https://llmstxt.org) is a site-root\n\n**index** of a website's content;\n\n`documentation.ai.md`\n\nis a per-product,\nper-release **operational manual**(closer to\n\n`llms-full.txt`\n\n). A site's\n`llms.txt`\n\ncan link to each product's `documentation.ai.md`\n\n. Adopt either\nindependently.Every [iwasoft](https://iwasoft.com) product ships a `documentation.ai.md`\n\nwith\neach release — real, published examples of the standard in practice.\n\n**See a real documentation.ai.md:**\n\nMore:\n\n**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\n[iwasoft.com](https://iwasoft.com)— each product's Documentation panel includes an**AI / LLM** entry.\n\nThe standard evolves in the open — see [CONTRIBUTING.md](/iwasoftcom/ai-docs-standard/blob/main/CONTRIBUTING.md). Open\nan issue to discuss a change; send a PR to propose one.\n\nThe AI Docs Standard is authored and stewarded by ** iwasoft**\nand released under\n\n[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:\n\n[iwasoft.com/standards/ai-docs](https://iwasoft.com/standards/ai-docs).", "url": "https://wpnews.pro/news/show-hn-documentation-ai-md-a-docs-standard-for-ai-agents-not-humans", "canonical_source": "https://github.com/iwasoftcom/ai-docs-standard", "published_at": "2026-08-29 20:22:29+00:00", "updated_at": "2026-08-29 20:48:48.894483+00:00", "lang": "en", "topics": ["ai-tools", "developer-tools", "ai-agents", "ai-products"], "entities": ["iwasoft", "AI Docs Standard", "AI Manifest Standard"], "alternates": {"html": "https://wpnews.pro/news/show-hn-documentation-ai-md-a-docs-standard-for-ai-agents-not-humans", "markdown": "https://wpnews.pro/news/show-hn-documentation-ai-md-a-docs-standard-for-ai-agents-not-humans.md", "text": "https://wpnews.pro/news/show-hn-documentation-ai-md-a-docs-standard-for-ai-agents-not-humans.txt", "jsonld": "https://wpnews.pro/news/show-hn-documentation-ai-md-a-docs-standard-for-ai-agents-not-humans.jsonld"}}