We started writing docs for AI agents, not humans — and made it an open standard
Most people install our tools through an agent now We build a few developer products — an event-ledger database, an S3-compatible object store, and others. Over the last few months we noticed a shift: most people who try them don't start in a browser. They tell a coding agent “add this to my project,” and the agent does the install and the wiring. So we started watching agents work against our…
Most users now install our tools through an agent. We develop several developer products, including an event-ledger database, an S3-compatible object store, and others. In recent months, we observed a shift: most individuals who attempt these tools do not begin in a browser. Instead, they instruct a coding agent to "add this to my project," and the agent handles the installation and wiring.
Consequently, we initiated monitoring of agents interacting with our documentation. Observing an agent's performance Most of the time, the agent performed well. However, occasionally, it would create a nonexistent configuration flag, select the incorrect port, or invoke an almost correct endpoint. The model was not incompetent; our documentation was written to persuade and onboard humans, while the agent was reconstructing facts from prose with gaps of three paragraphs.
A fact an agent must infer is a fact you omitted. Another document, for a distinct reader Therefore, we began distributing a supplementary file: documentation.ai.md. Not a condensed version of the human documentation — a separate document, designed for a different user, adhering to a higher standard of accuracy. Its structure is unambiguous, dense, and self-contained: an agent that has only read this file can install, configure, and utilize the product.
Organized sections in sequence: Identity declaration, Installation/execution - precise commands, exact image names and ports, Configuration - every environment variable / key, with its default value, API quickstart - a genuine request/response, not pseudo-code, Admin interface - how the first credential is obtained, common operations, Architecture facts that impact integration, Links, No promotional language; absolute honesty about status - if something is early or unverified, the file explicitly states this, as an agent recommending an unstable feature to a user due to misleading documentation would be a genuine failure.
"Why not just llms.txt?" A valid inquiry, and one we frequently receive. We are not attempting to supplant llms.txt. It is a superb site-wide index of your content. documentation.ai.md is a product-specific, release-specific operational document - akin to llms-full.txt in spirit: comprehensive, rather than an index. They work harmoniously.
We standardized it We successfully implemented this approach across our products, formally articulating it as an open standard (CC BY 4.0) so anyone can adopt it: GitHub: https://github.com/iwasoftcom/ai-docs-standard Write-up: https://iwasoft.com/blog/ai-docs-standard If you develop developer tools, your users - agents - are already perusing your documentation. This is merely providing the version they truly require.
Written by urgent.news from Dev.to's reporting — not their text. Machine-written — may contain errors; check the original before relying on it.
