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

> Source: <https://github.com/iwasoftcom/ai-docs-standard>
> Published: 2026-08-29 20:22:29+00:00

**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).