Diataxis: A Systematic Framework for Better Technical Documentation

Technical documentation is often an afterthought—a necessary evil that developers rush through. But documentation quality directly shapes developer experience, adoption, and the long-term maintainability of your project. If your documentation is confusing, scattered, or incomplete, users abandon your project. If it’s clear and well-organized, adoption accelerates.

Diataxis is a proven framework that solves this problem. Instead of writing documentation as it comes to mind, Diataxis organizes content into four distinct types, each serving a specific user need. The framework has been adopted by hundreds of projects—including Django and Stripe—and consistently improves documentation effectiveness. Others, like Kubernetes, reference Diataxis principles in their documentation structure.

This article covers what Diataxis is, why the four-type structure works, how to evaluate your existing documentation against it, and how to refactor your docs to follow the framework.

What Is Diataxis?

Diataxis (pronounced “die-uh-TAX-iss”) is a systematic approach to technical documentation created by Daniele Procida. It’s built on a simple observation: users approach documentation with different intents, and documentation serves different purposes. Conflating these purposes creates confusion.

The framework divides all documentation into four types:

Type	User Goal	Tone	Example
Tutorials	Learn the basics	Friendly, narrative	“Your First Django App”
How-to Guides	Accomplish a specific task	Direct, goal-focused	“How to Set Up Authentication”
Reference	Look up details	Concise, technical	“API Reference,” “Command-line Options”
Explanation	Understand the “why”	Educational, conceptual	“Why Django Uses Middleware,” “Architecture Overview”

Each type has distinct characteristics, and mixing them creates friction. A user trying to learn the basics doesn’t want a dense API reference. A user debugging a specific issue doesn’t want narrative tutorials. Diataxis keeps these purposes separate and creates a mental model that users can intuitively navigate.

The Four Documentation Types

1. Tutorials: Learning-Oriented Documentation

Tutorials are for people new to your tool or a particular feature. Their goal is to complete a meaningful first task, not to understand everything.

Characteristics:

• Narrative structure — tell a story, guide step-by-step
• Minimal conceptual burden — explain only what’s necessary for the immediate goal
• Success-oriented — the user should feel accomplishment at the end
• Concrete examples — real, working code that users can run

What tutorials should NOT do:

• Explain all options or edge cases (that’s what reference docs are for)
• Assume deep prior knowledge
• Switch between multiple tools or approaches (stay focused)
• Encourage experimentation outside the happy path

Example: Django Tutorials

Django’s official documentation includes “Writing Your First Django App,” which walks new developers through:

1. Creating a project
2. Creating an app
3. Writing models, views, and URL patterns
4. Accessing the admin interface

It follows a single, linear path. It doesn’t explain metaclasses, queryset caching, or middleware—those belong in explanatory docs. A new developer finishing this tutorial has a working Django app and understands the basic workflow.

2. How-To Guides: Problem-Oriented Documentation

How-to guides are for experienced users trying to accomplish a specific task. They assume competence and go straight to the solution.

Characteristics:

• Goal-driven — focus on the specific task, not comprehensive coverage
• Practical and direct — skip background, get to the steps
• Multiple valid approaches — acknowledge that different solutions exist for different contexts
• Assumes familiarity — the reader knows the basics

What how-to guides should NOT do:

• Assume the user is learning the tool for the first time
• Cover every possible variation (provide links to reference for details)
• Teach concepts—explain the task, not the why
• Replace reference documentation

Example: Django How-To Guides

“How to Implement Custom User Authentication” assumes the reader understands Django’s auth framework and wants to know how to extend it for a specific use case. It provides:

1. Define a custom user model
2. Create forms for registration and login
3. Configure settings
4. Wire up URLs

The guide is direct and goal-focused. It doesn’t re-explain how Django models work—that’s in reference docs and explanations.

3. Reference Documentation: Information-Oriented

Reference docs are lookup documentation—dense, structured, complete, and self-contained. A user consulting reference docs already knows what they’re looking for.

Characteristics:

• Complete and exhaustive — cover all options, parameters, return values, exceptions
• Concise and structured — organized for quick lookup, not reading from start to finish
• Neutral, objective tone — explain what exists, not why it’s useful
• No narrative flow — each entry stands alone

What reference docs should NOT do:

• Tell a story or build narrative understanding
• Explain use cases (that’s for how-to guides)
• Provide conceptual background (that’s for explanations)
• Assume the user is new to the tool

Example: Python API Reference

Python’s json module reference lists all functions and classes with:

• Parameter names and types
• Return types
• Exceptions that can be raised
• Concise descriptions

It doesn’t explain when to use json.dumps() vs. json.dump() (that’s a how-to question). It just defines what each does.

4. Explanation: Understanding-Oriented Documentation

Explanations help users understand the tool, its design philosophy, and the reasoning behind decisions. They build conceptual understanding.

Characteristics:

• Narrative and discursive — take time to explain ideas thoroughly
• Context-rich — provide background, history, and reasoning
• Conceptual focus — address “why” questions, not “how” questions
• Educational tone — help the reader build a mental model

What explanations should NOT do:

• Provide step-by-step instructions (that’s how-to guides)
• Serve as reference (that’s what reference docs are for)
• Assume the reader is new (they should have basic competence)
• Focus on accomplishing a specific task

Example: Django Explanations

“How Django Handles Request-Response Middleware” explains:

• Why middleware exists
• The order of execution
• How middleware fits into Django’s architecture
• Common patterns and anti-patterns

A developer reading this gains conceptual understanding. They might not need to use middleware today, but they’ll better understand Django’s design.

Why This Structure Works

The Diataxis framework works because it maps documentation types to user intent and cognitive modes:

1. Users approach docs with specific goals. Someone learning uses tutorials. Someone solving a problem uses how-to guides. Someone looking up a detail uses reference. Someone trying to understand the design reads explanations. Diataxis respects these different modes.

2. Mixing types creates confusion. A tutorial that pauses to explain every edge case becomes confusing. A reference document that starts with narrative explanations becomes harder to scan. Keeping types separate makes navigation intuitive.

3. Each type has distinct conventions. Users know what to expect from each type. A reference doc that starts with a conceptual explanation breaks those expectations. Consistency builds trust.

4. Organization becomes obvious. When you know what goes where, doc structure feels natural. New contributors know where to add their content.

Real-World Adoption: Who Uses Diataxis?

Hundreds of projects have adopted Diataxis, including:

• Django — Python web framework
• Python — Official Python documentation is actively exploring and mapping Diataxis principles for future improvements
• Kubernetes — References Diataxis principles in its documentation structure
• Stripe — Payment processing API
• Gatsby — React static site generator
• Cloudflare — CDN and DDoS protection
• Plone — Content management system

Each of these projects credits Diataxis with improving documentation clarity and reducing user confusion.

Auditing Your Existing Documentation

To apply Diataxis to your project, start by auditing your current docs:

Step 1: Categorize Existing Content

Go through your documentation and label each page or section:

• T = Tutorial
• H = How-to guide
• R = Reference
• E = Explanation

Don’t worry about precise categorization yet. Look for the primary intent.

Step 2: Identify Conflicts and Mixing

Flag content that violates the single-purpose principle:

• A how-to guide that starts with a 10-minute conceptual explanation
• A reference doc that includes step-by-step instructions
• A tutorial that attempts to cover every configuration option
• An explanation that reads like a reference document

Step 3: Spot Gaps

Ask: What types of content are missing?

• Do you have introductory tutorials for new users?
• Do you have how-to guides for common tasks?
• Is your reference complete and well-indexed?
• Do you explain design decisions and philosophy?

Step 4: Plan Refactoring

Create a simple table:

Current Doc	Current Type	Should Be	Refactoring Action
Getting Started	Attempts T+E	Separate into Tutorial (T) + Explanation (E)	Split the doc
API Reference	R mixed with H	Separate into Reference (R) + How-to (H)	Split or create sister docs
Deployment	Unclear	H	Refocus on the task, assume knowledge
Philosophy	Currently in README	E	Move to dedicated section

Refactoring doesn’t require rewriting everything. Often, you’re reorganizing and clarifying the purpose of existing content.

Practical Steps to Apply Diataxis

1. Start with Tutorials

If you don’t have tutorials, create one or two. A tutorial should take a new user from zero to “I built something that works.”

Example: Markdown documentation framework

# Getting Started with MyFramework

1. Install the package
2. Create your first document
3. Build and view the output
4. Customize a template

You've now completed your first MyFramework project!

2. Organize How-To Guides by Task

Group how-to guides by the problems they solve:

• “Configuring authentication”
• “Implementing custom fields”
• “Deploying to production”
• “Optimizing performance”

Each guide assumes the reader knows the basics.

3. Create a Complete Reference

Make sure your API reference is:

• Exhaustive — covers all public functions, classes, methods
• Indexed — users can find what they need
• Structured consistently — every entry follows the same template
• Linked — cross-references to related items

4. Document Design Philosophy and Reasoning

Write explanatory docs that help users understand:

• Why design decisions were made
• What problems the tool solves
• How components relate to each other
• When and where to use each feature

5. Link Types Together

Make navigation between types easy:

• Tutorials should link to related how-to guides
• How-to guides should link to reference docs for details
• Reference docs should link to explanations for context
• Explanations should link to tutorials for hands-on learning

Example linking flow:

Tutorial: "Your First App"
  ↓ (reader wants to know more)
How-To: "Add Authentication"
  ↓ (reader needs exact API parameters)
Reference: "Authentication API"
  ↓ (reader wants to understand design)
Explanation: "Why Authentication is Middleware"

Tools and Workflows for Maintaining Diataxis Structure

Documentation Linting and Structure Validation

Tools to enforce Diataxis structure:

• Markdownlint + custom rules — enforce consistent frontmatter and structure
• Doctave — documentation framework with built-in Diataxis support
• Sphinx — Python documentation generator with custom directives for doc types
• MkDocs with plugins — extensible static site generator

Collaboration Practices

• Clear labeling — label PRs and issues by doc type (docs: tutorial, docs: how-to)
• Review guidelines — reviewers check that content matches its intended type
• Contribution templates — guide contributors to the right doc type
• Content inventory — maintain a spreadsheet or structured list of all docs and their types

Versioning and Maintenance

• Archive old tutorials — keep deprecated tutorials separated
• Update reference docs automatically — use code comments or docstrings to auto-generate reference
• Monitor outdated how-to guides — flag guides that reference deprecated features
• Refresh explanations periodically — ensure they reflect current design decisions

Relationship to Other Documentation Standards

Diataxis complements other documentation practices:

Diataxis vs. Write the Docs Best Practices

Write the Docs covers tone, style, and audience. Diataxis covers structure and purpose. Use both: Diataxis tells you what to write, and Write the Docs guides tell you how to write it.

Diataxis and Documentation Accessibility

Accessibility (WCAG) and Diataxis address different concerns:

• Accessibility ensures content is accessible to people with disabilities
• Diataxis ensures content is organized for different user intents

Apply both: make your docs accessible and well-organized.

Diataxis and API Documentation Tools

Tools like Swagger, OpenAPI, and Javadoc auto-generate reference docs. Diataxis tells you how to supplement that reference with tutorials, how-to guides, and explanations—the parts auto-generation can’t create.

Getting Started with Diataxis Today

1. Visit diataxis.fr for the official guide and examples
2. Audit your current docs against the four types
3. Identify the highest-impact gaps (missing tutorials, unclear reference, etc.)
4. Start small — improve one section to demonstrate the benefit
5. Involve your team — discuss the framework and plan adoption together
6. Iterate — good documentation is never “done”; Diataxis provides a framework for continuous improvement

Frequently Asked Questions

Q: Should we refactor our documentation all at once or incrementally?
A: Incremental refactoring is recommended. Start with one high-traffic section (e.g., getting-started guide), apply Diataxis principles, and measure the impact before scaling. This allows your team to learn the framework without overwhelming existing workflows.

Q: How does Diataxis compare to DITA (Darwin Information Typing Architecture)?
A: Diataxis is simpler and user-intent-focused, designed for open-source and technical projects. DITA is enterprise-focused with more rigid structure and broader customization for content reuse. Choose Diataxis for agility; choose DITA for large-scale enterprise documentation.

Q: Which documentation type should we write first when adopting Diataxis?
A: Start with tutorials if you lack them (they’re the highest-impact for new user adoption). If you already have tutorials, prioritize how-to guides for common tasks. Reference docs usually exist in some form; focus on reorganization over rewriting.

Q: Can a single page contain multiple documentation types?
A: Avoid mixing types on one page—it creates navigation friction. Instead, create separate pages and link them together. A page can link to multiple types (e.g., a tutorial that links to reference docs), but the page itself should serve a single purpose.

Q: How do we measure if our Diataxis refactoring is working?
A: Track user behavior: time-to-first-success in tutorials, task-completion rates in how-to guides, and reference-doc lookup patterns. Conduct user interviews asking whether docs matched their intent. Survey users on navigation clarity and satisfaction before and after refactoring.

See Also

• API Design Patterns: Architecture — Documentation patterns in API design
• Docker Best Practices: Containerization — Documentation as a teaching tool for infrastructure

Conclusion

Diataxis transforms documentation from a frustrating afterthought into a strategic asset. By organizing content into four types—each serving a specific user need—you create documentation that’s intuitive to navigate, easier to maintain, and more likely to be read and understood.

Whether you’re building an open-source library, an internal tool, or a developer platform, Diataxis provides a proven framework for creating documentation that works. Start with an audit of your current docs, identify gaps, and gradually refactor toward the framework. Your users—and your project’s adoption rate—will thank you.