{"slug": "we-started-writing-docs-for-ai-agents-not-humans-and-made-it-an-open-standard", "title": "We started writing docs for AI agents, not humans — and made it an open standard", "summary": "A developer tools company has introduced an open standard for writing documentation specifically for AI agents, called documentation.ai.md. The standard, released under CC BY 4.0, is a per-product, per-release operational doc that is dense, self-sufficient, and free of marketing language, ensuring agents can install, configure, and call products without human inference. The company observed that agents often hallucinate config flags or endpoints due to human-oriented docs, prompting the creation of this stricter format.", "body_md": "We build a few developer products — an event-ledger database, an S3-compatible\n\nobject store, and others. Over the last few months we noticed a shift: most\n\npeople who try them don't start in a browser. They tell a coding agent “add this\n\nto my project,” and the agent does the install and the wiring.\n\nSo we started watching agents work against our documentation.\n\nMost of the time it went fine. But every so often the agent would invent a\n\nconfig flag that didn't exist, or reach for the wrong port, or call an endpoint\n\nthat was *almost* right. It wasn't the model being dumb — our docs were written\n\nto persuade and onboard a **human**, and the agent was reconstructing facts from\n\nprose three paragraphs apart. A fact an agent has to infer is a fact you failed\n\nto state.\n\nSo per release we started shipping a second file: `documentation.ai.md`\n\n. Not a\n\nterser translation of the human docs — a different document, for a different\n\nreader, held to a stricter standard of precision.\n\nIt's English, dense, and self-sufficient: an agent that has read *only* that file\n\ncan install, configure and call the product. Fixed sections, in order:\n\nNo marketing language. Absolute honesty about status — if something is early or\n\nunaudited, the file says so, because an agent that recommends an unstable feature\n\nto a user because the doc oversold it is a real failure.\n\nFair question, and we get it a lot. We're not trying to replace\n\n[llms.txt](https://llmstxt.org). It's a great *site-level index* of your content.\n\n`documentation.ai.md`\n\nis a *per-product, per-release operational doc* — closer in\n\nspirit to `llms-full.txt`\n\n: complete, not an index. They compose cleanly.\n\nIt worked well enough across our products that we wrote it up as an open standard\n\n(CC BY 4.0), so anyone can adopt it:\n\nIf you build developer tools, your users' agents are already reading your docs.\n\nThis is just writing the version they actually need.", "url": "https://wpnews.pro/news/we-started-writing-docs-for-ai-agents-not-humans-and-made-it-an-open-standard", "canonical_source": "https://dev.to/kissoid/we-started-writing-docs-for-ai-agents-not-humans-and-made-it-an-open-standard-3ija", "published_at": "2026-08-30 07:50:56+00:00", "updated_at": "2026-08-30 08:22:25.849066+00:00", "lang": "en", "topics": ["developer-tools", "ai-agents", "ai-tools"], "entities": [], "alternates": {"html": "https://wpnews.pro/news/we-started-writing-docs-for-ai-agents-not-humans-and-made-it-an-open-standard", "markdown": "https://wpnews.pro/news/we-started-writing-docs-for-ai-agents-not-humans-and-made-it-an-open-standard.md", "text": "https://wpnews.pro/news/we-started-writing-docs-for-ai-agents-not-humans-and-made-it-an-open-standard.txt", "jsonld": "https://wpnews.pro/news/we-started-writing-docs-for-ai-agents-not-humans-and-made-it-an-open-standard.jsonld"}}