Diátaxis Framework

Diátaxis is a systematic framework for organizing documentation into four distinct categories, each serving a specific user need and context. The framework ensures that documentation becomes more discoverable, navigable, and effective by addressing the full spectrum of how people learn and use software.

What is Diátaxis

Diátaxis (pronounced “die-uh-TAK-sis”) is a framework created by Daniele Procida that organizes documentation into four quadrants based on two dimensions: whether content is practical or theoretical, and whether it is for learning or working. This structure acknowledges that different users have different needs at different times—someone learning a new framework needs step-by-step guidance, while an experienced developer needs quick reference lookup. By separating these needs into distinct content types, documentation becomes more focused, easier to navigate, and more effective for everyone.

The framework has become a standard in technical documentation because it solves a common problem: mixing all content types together creates documentation that is confusing for both learners and experienced users. Diátaxis provides a proven architecture for organizing thousands of pages into a coherent, user-centric system.

Tutorials vs Guides

Tutorials are learning-oriented content designed to introduce newcomers to a subject through concrete, hands-on experience. A tutorial holds the reader’s hand from start to finish, following a predetermined path with specific, actionable steps. Success is measured by completion: the reader finishes the tutorial with a working understanding of the fundamentals, even if they don’t fully understand why each step matters.

Guides (sometimes called “How-to” documentation) are task-focused and practical. They assume the reader already understands the basics and wants to accomplish a specific goal. A guide answers “How do I do X?” with direct, efficient procedures. The reader can jump to any section and find the information they need without needing context from earlier chapters. Unlike tutorials, guides are optional—readers use them to solve particular problems, not to gain foundational knowledge.

The key distinction: tutorials create competence through structured learning; guides solve specific problems through direct instruction.

Reference Documentation

Reference documentation is the lookup layer of your docs—organized alphabetically, hierarchically, or by API structure, it provides complete technical information without explanation. A reader consulting reference documentation already knows what they’re looking for; they need accurate, comprehensive details presented in a consistent format.

Effective reference pages follow an outline structure rather than narrative flow. Each entry (function, class, parameter, option) receives clear documentation of its signature, parameters, return values, and usage constraints. Reference is not the place for extended examples or conceptual background—those belong in guides or explanations. Reference succeeds when developers can find exactly what they need in seconds, without reading unnecessary context.

Conceptual Explanations

Explanations (also called “Concepts”) are understanding-oriented content that answers “Why?” and “What does this mean?” rather than “How do I?” They provide the mental models, background knowledge, and reasoning behind system design that helps developers make better decisions. A conceptual explanation might explore why a framework uses a particular architecture, how different components interact, or the trade-offs between alternative approaches.

Explanations are not tutorials (they don’t guide you step-by-step) and not reference (they don’t catalog every option). Instead, they illuminate the thinking and context around your system. They’re essential for helping experienced developers understand your tool deeply and for preventing misuse that stems from incomplete mental models.

Applying to Your Docs

Start by auditing your existing documentation and asking: Why am I reading this? Is the reader trying to get started (tutorial), solve a specific problem (guide), look something up (reference), or understand concepts (explanation)? Reorganize content into these four categories, removing it from mixed sections where it causes confusion.

Implement structural markers so readers know what type of content they’re reading. Use consistent formatting: tutorials include step indicators, guides use numbered procedures with clear sections, reference uses API-style documentation, and explanations use narrative with headings that reveal structure.

In docs-mcp, the pipeline implements Diátaxis by organizing generated topics into these categories during the planning phase, ensuring that both hand-authored and LLM-generated content follows this proven framework for maximum clarity and discoverability.

The key distinction is about the reader’s goal:

Tutorial: “I want to learn this thing.” The reader doesn’t have a specific task in mind — they’re building understanding. You lead them by the hand through a carefully designed learning experience. You choose what they build, you control the scope, and the outcome is that they’ve learned something, not necessarily that they’ve produced something useful. Think “learn to cook” — you pick the recipe, you explain why you’re searing before braising, you build up their intuition.

How-to guide: “I need to do this thing.” The reader already has a specific goal and some baseline competence. They don’t need you to explain why — they need the steps to get from A to B. Think “recipe” — it assumes you know what a sauté is, it doesn’t teach you knife skills, it just tells you how to make the dish.

The practical differences that fall out of this:

A tutorial can’t assume much prior knowledge and should be completable start-to-finish in a single sitting. A how-to can assume the reader knows the basics and can be as short as a checklist.

A tutorial picks a contrived but illustrative example that maximizes learning. A how-to addresses a real-world problem the reader actually has right now.

A tutorial says “let’s create a simple auth flow so you understand how passkeys work.” A how-to says “how to add FIDO2 passkey registration to your existing SolidStart app.”

The gray area — and where your “How to configure from scratch” lives — is when a how-to is so comprehensive that it starts feeling like a tutorial. The litmus test: if you’re explaining why things work along the way, it’s drifting toward tutorial. If you’re just saying what to do and the reader could skip steps they’ve already done, it’s a how-to.