Diátaxis Has Four Quadrants. AI Agents Need a Fifth.
The Diátaxis framework solved documentation structure for humans. But AI agents don't read docs like humans do — they execute them. That changes everything about how documentation should be organized.
Diátaxis Has Four Quadrants. AI Agents Need a Fifth.
There’s a framework that’s become the gold standard for documentation structure. It’s called Diátaxis, and if you’ve spent any time in technical writing circles, you’ve encountered it. It divides documentation into four quadrants: tutorials, how-to guides, reference, and explanation.
Diátaxis is good. It’s genuinely useful. It gives technical writers a vocabulary for thinking about what kind of documentation they’re writing and why. It’s been upvoted on Hacker News, adopted by major open-source projects, and cited in enough blog posts to qualify as industry consensus.
But Diátaxis was designed for humans. And humans aren’t the only consumers of your documentation anymore.
The Four Quadrants (A Quick Refresher)
Diátaxis maps documentation along two axes: action vs. theory and user-acquired knowledge vs. user intent. The result is four distinct types:
Tutorials — Learning-oriented. Take a beginner by the hand. Goal: acquire skills, not solve a specific problem.
How-to guides — Problem-oriented. Show someone how to accomplish a specific task. Goal: solve a problem the user already understands.
Reference — Information-oriented. Describe the machinery. Endpoints, parameters, error codes, configuration options. Goal: look something up.
Explanation — Understanding-oriented. Explain why things work the way they do. Design decisions, architecture, trade-offs. Goal: deepen understanding.
Each type serves a different purpose. Each has a different structure. And most importantly, each requires a different writing approach. A tutorial teaches. A reference explains. A how-to guides. An explanation contextualizes.
For human readers, this works great. It maps to how people actually use documentation: sometimes you’re learning, sometimes you’re stuck, sometimes you’re looking something up, sometimes you want to understand the bigger picture.
The Problem: AI Agents Don’t Have Intent
Here’s what breaks when AI agents enter the picture: Diátaxis assume the reader has intent. A human picks up a tutorial because they want to learn. They grab a how-to guide because they have a problem. They consult a reference because they need a specific detail.
AI agents don’t have intent. They have context windows.
When Claude Code ingests your documentation, it doesn’t choose which quadrant to read based on what it’s trying to do. It ingests everything it can fit into its context window and then tries to generate code based on whatever it absorbed. It doesn’t distinguish between your carefully crafted tutorial and your auto-generated API reference. It doesn’t know that the explanation section is conceptual and the reference section is authoritative.
This creates a structural problem that Diátaxis doesn’t address: your documentation has implicit reliability gradients that AI agents can’t see.
The Reliability Gradient
Not all documentation is created equal — and not all documentation deserves the same level of trust when an AI agent is generating code from it.
Consider the typical documentation set for a REST API:
- API reference (auto-generated from OpenAPI spec) — High reliability. Structured. Machine-readable. Directly tied to the code.
- Getting started tutorial (hand-written, updated quarterly) — Medium reliability. Structured for learning, may contain outdated examples.
- How-to guides (community-contributed, rarely reviewed) — Variable reliability. May work. May be from two API versions ago.
- Conceptual explanation (written once, never updated) — Low reliability for code generation. Useful for understanding. Dangerous for execution.
Humans navigate this reliability gradient intuitively. We know that the API reference is the source of truth. We know that the community how-to might be outdated. We know that the tutorial’s example code was written for v1 and we’re now on v3.
AI agents don’t know any of this. They treat a v1 tutorial example with the same weight as an auto-generated OpenAPI reference. They’ll happily generate code based on your outdated community how-to because it was the first result in the context window.
The Fifth Quadrant: Contracts
What’s missing from Diátaxis is a fifth quadrant for the AI era: contracts.
A contract is documentation that is machine-validated against the source of truth. It’s not just reference documentation — reference docs can drift too. A contract is documentation that has been explicitly validated to match the code it describes. It carries a guarantee: this is accurate because it was checked, not because someone wrote it carefully.
The four Diátaxis quadrants answer the question: What kind of content is this?
The fifth quadrant answers a different question: Is this accurate?
Here’s what the five-quadrant model looks like:
| Quadrant | Purpose | Audience | Validation |
|---|---|---|---|
| Tutorials | Teach skills | Humans | Manual review |
| How-to guides | Solve problems | Humans | Manual review |
| Reference | Describe machinery | Humans + agents | Semi-automated |
| Explanation | Provide context | Humans | Manual review |
| Contracts | Guarantee accuracy | AI agents | Automated, continuous |
Contracts sit alongside the other four quadrants. They don’t replace them. A contract version of your API reference is just your API reference — but validated against your actual OpenAPI spec, checked for parameter accuracy, and continuously monitored for drift.
Why This Matters Now
Two things are happening simultaneously in the developer tools landscape.
First, AI coding agents are becoming the primary consumers of API documentation. Tools like Claude Code, Cursor, and GitHub Copilot don’t just suggest code — they generate it based on your docs. The documentation is no longer a reference. It’s a specification that gets executed.
Second, the documentation itself is increasingly AI-generated. Teams are using LLMs to auto-generate API references, write tutorials, and produce how-to guides. This creates a recursive problem: AI writes the docs, AI reads the docs, and nobody validates the cycle.
In a world where AI is both the writer and the reader of documentation, the accuracy question becomes existential. You can have perfectly structured Diátaxis-compliant documentation that is also perfectly wrong. Structure doesn’t guarantee accuracy. Neither does AI generation. Only validation does.
What This Means for Your Documentation
You don’t need to abandon Diátaxis. You need to layer validation on top of it.
For each of the four quadrants, ask: what’s the accuracy guarantee?
- Tutorials: When was the last time someone ran the example code?
- How-to guides: Do these steps still work on the current version?
- Reference: Does this match the actual API schema?
- Explanation: Are the design decisions described still current?
These are validation questions, not writing questions. And they can’t be answered by reading — they can only be answered by testing. Running the code. Checking the schema. Comparing the docs to the source.
This is what it means to add a contract layer to your documentation. You’re not reorganizing the content. You’re adding a validation signal that both humans and AI agents can use to determine: is this trustworthy?
The Boring Part
Here’s the thing about contracts: they’re boring to create. Running code examples. Checking parameter names. Comparing error codes to actual responses. Validating that tutorial screenshots match the current UI.
Nobody wants to do this manually. It’s tedious. It’s repetitive. It’s exactly the kind of work that should be automated.
That’s the boringdocs thesis, stated differently: Diátaxis gives you the right structure for documentation. Contracts give you the right verification. Structure without verification is just organized drift.
The AI era doesn’t need better documentation frameworks. It needs documentation that comes with accuracy guarantees. Not “we wrote this carefully” but “we validated this continuously.”
Four quadrants for humans. A fifth for the machines. And a validation layer that keeps all five honest.
Your documentation has structure. Does it have guarantees? Join the waitlist — the validation layer that keeps your docs accurate, for every quadrant.