Optimizing Documentation for the AI Agent Era
The traditional standard for technical documentation has always been based on human intuition: if a developer can eventually figure it out, the docs are considered 'good.' However, as AI coding agents become the primary interface for interacting with software, this standard is no longer sufficient. Ambiguity that a human might intuitively bridge is a failure point for an agent.
dari-docs is a CLI tool designed to shift documentation quality from a subjective feeling to a measurable metric. By using fleets of simulated developer agents to attempt real tasks using only the provided documentation, it creates a repeatable feedback loop for creating 'agent-readable' documentation.
The Shift Toward Agent-Readable Documentation
When the reader is an AI agent, the cost of ambiguity increases. Inconsistent terminology, hidden assumptions, and missing setup steps are not just minor inconveniences; they are blockers that cause agents to fail tasks or waste context windows trying to infer missing information.
dari-docs addresses this by treating documentation as code that needs to be tested. It allows developers to define a concrete task—such as "Install the SDK and make a first API call"—and then observes whether a simulated agent can successfully complete that task using only the documentation provided.
Core Functionality and Workflow
The tool operates through a primary feedback loop: test, inspect, and optimize.
1. Testing with Simulated Developers
Using the dari-docs check command, users can point the tool at a local directory or a public URL. The CLI bundles the documentation and submits it to tester agents. These agents attempt the specified task and report exactly where they got stuck, identifying missing context or unclear setup instructions.
2. Identifying Blockers
Rather than a general review, dari-docs provides specific feedback on task-blocking ambiguity. This includes:
- Missing Context: Steps that are assumed but not explicitly stated.
- Inconsistent Terms: Different names for the same concept, which can confuse an agent's reasoning.
- Unclear Setup: Prerequisites that are not clearly defined.
3. Automated Optimization
Beyond just identifying problems, the tool offers an optimize command. This triggers an editor agent that proposes specific documentation edits based on the failures encountered by the tester agents. These proposed changes are downloaded into a .dari-docs/updated/ folder for human review, ensuring that the user maintains control over the final content.
Deployment Modes: Managed vs. Self-Managed
To accommodate different needs, dari-docs offers two execution paths:
| Mode | Use Case | Requirements |
|---|---|---|
| Managed | Fastest setup and hosted execution. | dari-docs auth login |
| Self-managed | Runs within your own dari.dev organization for more control. | dari.dev API key and deployed agents |
Community Perspectives and Considerations
While the agents-testing-docs approach is praised for making debugging more practical, the community has raised several critical points regarding its implementation in real-world pipelines:
"I think one feature that would make dari-docs significantly more practical for real-world pipelines is a robust, built-in bidirectional converter between Markdown and HTML"
Additionally, some users have expressed concerns regarding the sensitivity of uploading documentation to a hosted service, a point that highlights the importance of the self-managed mode for enterprises with strict data privacy requirements.
Conclusion
As we move toward a world where AI agents are more likely to read your documentation than humans, the goal is to make docs "so good even the dumbest agent can ship." By treating documentation as a testable asset, dari-docs provides a framework for turning ambiguity into a measurable failure, allowing developers to build software that is truly accessible to the AI-driven development lifecycle.