We started writing docs for AI agents, not humans — and made it an open standard

Description and use

A machine‑readable documentation format was created to enable AI agents to install and configure products reliably, published as an open standard.

Problem

Developer documentation written for humans caused AI agents to misinterpret or invent configuration details, leading to installation and integration failures.

Outcome

Agents could reliably install and configure products using the new machine‑readable docs, reducing errors and improving developer experience.

Workflow

• 1. Observe agents interacting with existing docs and identify missteps.
• 2. Identify missing or ambiguous facts that agents must infer.
• 3. Create a new per‑product, per‑release file (documentation.ai.md).
• 4. Structure the file into fixed sections: identity, install/run, configuration, API quickstart, admin surface, architecture facts, links.
• 5. Ensure each section contains exact commands, env vars, defaults, and real request/response examples.
• 6. Publish the file alongside the human‑oriented docs.
• 7. Release the format as an open standard (CC BY 4.0).

Evidence

We started watching agents work against our documentation.

Source

A fact an agent has to infer is a fact you failed to state.

Source