Have you ever tried to follow a “Quickstart” guide that suddenly veered into a deep discussion of system architecture? Or looked for a simple command in an API reference only to find it buried in a long, narrative tutorial?
This common problem is often called “content chaos” or “content sprawl.”
It happens when different kinds of information are mixed together without a clear structure.
Introductory lessons, troubleshooting steps, conceptual deep dives, and technical specifications all get tangled into a single, confusing web.
For a user, this is frustrating; it makes it incredibly difficult to find the right information at the right time.
To solve this, you can use the Diátaxis framework, developed by Daniele Proceda, that is a systematic approach to organising documentation.
This framework can transform your portal from a simple content repository into a purposeful, user-centric information system designed for developer success.
Free guide to implementing Diátaxis
Diátaxis infographic
What is the Diátaxis framework?
The Diátaxis framework is a systematic solution to this problem. It is a approach for organising technical documentation effectively.
Its core purpose is simple but powerful: Diátaxis organises documentation not by topic, but by user need.
Mapping documentation to intent
Diátaxis is built on the simple insight that people approach documentation with different goals at different times. The framework maps these goals along two axes to create a clear structure for content:
-
Practical v. Theoretical
-
Is the user trying to do something, or are they trying to know something?
-
-
Acquisition v. Application
-
Is the user trying to acquire new skills, or are they trying to apply skills they already have?
-
About the four quadrants
These two axes create four distinct quadrants, each representing a specific user need and a corresponding type of documentation.
This table is the foundational map for the entire framework.
| Practical (Doing) | Theoretical (Knowing) | |
|---|---|---|
| Acquisition (Acquiring skills) | Tutorials (Learning-oriented) | Explanation (Understanding-oriented) |
| Application (Applying skills) | How-to Guides (Task-oriented) | Reference (Information-oriented) |
How it works in practice
Deconstructing a single topic
Let’s take a common documentation topic: “User Authentication.”
In a traditional, unstructured system, all the information about authentication (the theory, the setup steps, and the API endpoint details) might be mixed into one long, confusing page.
With Diátaxis, this topic is split into four clear, focused documents, each serving a single purpose.
The four documents for “User Authentication”
| Document type | Title and purpose |
|---|---|
| Tutorial | “Build a Login Form in 10 Minutes”: A step-by-step lesson that gets a new user to a working login form, without explaining the deep theory of security models. |
| How-to Guide | “How to Implement OAuth 2.0 in Your Web App”: A practical recipe with code samples showing an experienced developer the exact steps to integrate a specific authentication flow. |
| Reference | “/oauth2/authorise Endpoint”: A dry, factual description of every parameter, response field, and error code for the authorisation endpoint. |
| Explanation | “Understanding Our Security Model: OAuth 2.0, Scopes, and Permissions”: A conceptual article explaining why the system uses OAuth 2.0 and how it works under the hood. |
The user’s journey
The true power of this system comes from intentional cross-linking.
The “Build a Login Form” Tutorial would link to the “How to Implement OAuth 2.0” How-To Guide as a “Next Step.”
That guide, in turn, would link key technical terms like response_type to the Reference docs for the /oauth2/authorise endpoint.
It would also include a “Want to know more?” link pointing to the Explanation on the security model.
This deliberate signposting allows users to self-select the depth they need at any given moment, creating a fluid journey from learning to doing to understanding.
Why this matters for your users and you
The core benefit: Respecting the user’s intent
The primary benefit of the Diátaxis framework is that it respects the user. It acknowledges that a person’s needs change – the goal of a beginner learning for the first time is fundamentally different from that of an expert debugging a problem. By structuring content around these needs, Diátaxis ensures that every user gets the right information for their current goal, leading to a more efficient, less frustrating experience. For the organisation, this translates directly into faster developer onboarding, reduced support load, and ultimately, greater platform adoption.
-
The most effective documentation is structured around what the user is trying to accomplish (learn, do, know, or understand).
-
Organise by need, not by topic.
-
-
Tutorials teach; How-to guides solve problems; Reference pages describe; Explanations provide context.
-
Mixing these purposes creates confusion. Each document has one job.
-
-
If you need help
If you need help in implementing Diátaxis, Cherryleaf can help you.
We offer instructor-led training courses where we can cover Diátaxis. We can provide you with additional writers who can help you with modifying your existing Knowledge Base and content, and cretaing new content that follows the Diátaxis framework.
We have also developed some AI-drive apps for managing a Diátaxis migration project.
Contact Cherryleaf to discuss your situation.