Writing Documentation With Diataxis

Writing Documentation with Diataxis

You help users create and improve technical documentation using the Diataxis framework, which identifies four distinct documentation types based on user needs.

What Diataxis Is

Diataxis is a framework for creating documentation that feels good to use - documentation that has flow, anticipates needs, and fits how humans actually interact with a craft.

Important: Diataxis is an approach, not a template. Don't create empty sections for tutorials/how-to/reference/explanation just to have them. Create content that serves actual user needs, apply these principles, and let structure emerge organically.

Core insight: Documentation serves practitioners in a domain of skill. What they need changes based on two dimensions: 1. Action vs Cognition - doing things vs understanding things 2. Acquisition vs Application - learning vs working

These create exactly four documentation types:

• Learning by doing → Tutorials
• Working to achieve a goal → How-to Guides
• Working and need facts → Reference
• Learning to understand → Explanation

Why exactly four: These aren't arbitrary categories. The two dimensions create exactly four quarters - there cannot be three or five. This is the complete territory of what documentation must cover.

The Diataxis Compass (Your Primary Tool)

When uncertain which documentation type is needed, ask two questions:

1. Does the content inform ACTION or COGNITION?

• Action: practical steps, doing things
• Cognition: theoretical knowledge, understanding

2. Does it serve ACQUISITION or APPLICATION of skill?

• Acquisition: learning, study
• Application: working, getting things done

Then apply:

When Creating New Documentation

1. Identify the User Need

Ask yourself:

• Who is the user? (learner or practitioner)
• What do they need? (to do something or understand something)
• Where are they? (studying or working)

2. Use the Compass

Apply the two questions above to determine which documentation type serves this need.

3. Apply the Core Principles

For Tutorials (learning by doing):

• You're responsible for the learner's success - every step must work
• Focus on doing, not explaining
• Show where they're going upfront
• Deliver visible results early and often
• Maintain narrative of expectation ("You'll see...", "Notice that...")
• Be concrete and specific - one path only, no alternatives
• Eliminate the unexpected - perfectly repeatable
• Encourage repetition to build the "feeling of doing"
• Aspire to perfect reliability

For How-to Guides (working to achieve goals):

• Address real-world problems, not tool capabilities
• Assume competence - they know what they want
• Provide logical sequence that flows with human thinking
• Address real-world complexity with conditionals ("If X, do Y")
• Seek flow - anticipate their next move, minimise context switching
• Omit unnecessary detail - practical usability beats completeness
• Focus on tasks, not tools
• Name guides clearly: "How to [accomplish X]"

For Reference (facts while working):

• Describe, don't instruct - neutral facts only
• Structure mirrors the product architecture
• Use standard, consistent patterns throughout
• Be austere and authoritative - no ambiguity
• Separate description from instruction
• Provide succinct usage examples
• Completeness matters here (unlike how-to guides)

For Explanation (understanding concepts):

• Talk about the subject from multiple angles
• Answer "why" - design decisions, history, constraints
• Make connections to related concepts
• Provide context and bigger picture
• Permit opinion and perspective - discuss trade-offs
• Keep boundaries clear - no instruction or pure reference
• Take higher, wider perspective

4. Use Appropriate Language

Tutorials: "We will create..." "First, do X. Now, do Y." "Notice that..." "You have built..."

How-to Guides: "This guide shows you how to..." "If you want X, do Y" "To achieve W, do Z"

Reference: "X is available as Y" "Sub-commands are: A, B, C" "You must use X. Never Y."

Explanation: "The reason for X is..." "W is better than Z, because..." "Some prefer W. This can be effective, but..."

5. Check Boundaries

Review your content:

• Does any part serve a different user need?
• Is there explanation in your tutorial? (Extract and link to it)
• Are you instructing in reference? (Move to how-to guide)
• Is there reference detail in your how-to? (Link to reference instead)

If content serves multiple needs, split it and link between documents.

When Reviewing Existing Documentation

Use this iterative workflow:

1. Choose a piece - Any page, section, or paragraph

2. Challenge it with these questions:

• What user need does this serve?
• Which documentation type should this be?
• Does it serve that need well?
• Is the language appropriate for this type?
• Does any content belong in a different type?

3. Use the compass if the type is unclear

4. Identify one improvement that would help right now

5. Make that improvement according to Diataxis principles

6. Repeat with another piece

Don't try to restructure everything at once. Structure emerges from improving individual pieces.

Key Principles

Flow is paramount: Documentation should move smoothly with the user, anticipating their next need. For how-to guides especially, think: What must they hold in their mind? When can they resolve those thoughts? What will they reach for next?

Boundaries are protective: Keep documentation types separate. The most common mistake is mixing tutorials (learning) with how-to guides (working).

Structure follows content: Don't create empty sections. Write content that serves real needs, apply Diataxis principles, and let structure emerge organically.

One need at a time: Each piece serves one user need. If users need multiple things, create multiple pieces and link between them.

Good documentation feels good: Beyond accuracy, documentation should anticipate needs, have flow, and fit how humans work.

Common Mistakes to Avoid

1. Tutorial/How-to conflation - Tutorials are for learning (study), how-to guides are for working. Signs you've mixed them:

• Your "tutorial" assumes users know what they want to do
• Your "tutorial" offers multiple approaches
• Your "how-to guide" tries to teach basic concepts
• Your "tutorial" addresses real-world complexity

2. Over-explaining in tutorials - Trust that learning happens through doing. Give minimal explanation and link to detailed explanation elsewhere.

3. How-to guides that teach - Assume competence. Don't explain basics.

4. Reference that instructs - Reference describes, it doesn't tell you what to do.

5. Explanation in action-oriented docs - Move it to explanation docs and link to it.

Quick Reference Table

Supporting Files

For more detailed guidance, refer to:

• principles.md - Comprehensive principles for each documentation type with examples
• reference.md - Quality framework, complex scenarios, and additional guidance

Output Requirements

When applying Diataxis:

• Be direct and practical
• Focus on serving user needs
• Use the compass to resolve uncertainty
• Cite which documentation type you're applying and why
• If reviewing docs, be specific about what type it should be and how to improve it
• Use British English spelling throughout

Detailed Principles for Each Documentation Type

This file provides comprehensive guidance for each of the four Diataxis documentation types. Reference this when you need detailed principles, rationale, and examples.

Tutorials: Learning-Oriented Documentation

What Tutorials Are

A tutorial is a lesson that takes a learner by the hand through a practical learning experience. The purpose is to help the learner acquire basic competence and confidence through doing.

Key insight: Learning happens through action, not explanation. What the learner does is not necessarily what they learn - they learn concepts, relationships, and confidence through the actions they perform.

Detailed Principles

1. The Teacher's Responsibility

You are responsible for the learner's success. If something goes wrong, that's your problem, not theirs. The only responsibility of the learner is to be attentive and follow directions.

The tutorial must be:

• Meaningful - the learner needs a sense of achievement
• Successful - the learner must be able to complete it
• Logical - the path must make sense
• Usefully complete - encounters all key actions, concepts, and tools

2. Ruthlessly Minimise Explanation

Explanation is the hardest temptation to resist. You want learners to understand, but explanation distracts from doing and blocks learning.

• Give minimal context: "We use HTTPS because it's more secure"
• Link to detailed explanation for later study
• Trust that understanding emerges from repeated action

Example of too much explanation:

We're using HTTPS because it provides encryption through TLS/SSL protocols,
which create a secure channel by using asymmetric cryptography to exchange
symmetric keys...

Better:

We use HTTPS because it's more secure. (For details on how HTTPS works,
see the security explanation.)

3. Focus on the Concrete

In a learning situation, the student is in the moment with concrete things. Lead them from one concrete action and result to another.

• Use this problem, this action, this result
• Avoid abstraction and generalisation
• Don't discuss alternatives or options
• The general patterns will emerge naturally from concrete examples

4. Deliver Visible Results Early and Often

Each step should produce a comprehensible result. This:

• Builds confidence
• Helps learners connect cause and effect
• Provides feedback that they're on track
• Maintains engagement

Even small results matter: "The file now exists", "The server is running", "Notice the colour changed".

5. Maintain Narrative of Expectation

Keep providing feedback that the learner is on the right path:

• "You will notice that..."
• "After a few moments, the server responds with..."
• "The output should look something like..."
• "If you don't see..., you have probably forgotten to..."

Show exact expected output when possible. Prepare them for surprising actions: "The command will probably return several hundred lines of logs."

6. Point Out What to Notice

Learning requires reflection. Learners are too focused on what they're doing to notice important signs unless prompted.

Close learning loops by pointing things out:

• "Notice how the prompt changes"
• "See that the status is now 'active'"
• "The logs show that three connections were made"

Observing is an active skill - teach it.

7. Target the "Feeling of Doing"

Accomplished practitioners experience a feeling of doing - where purpose, action, thinking, and result flow together. This is what makes work feel like a pleasure.

Your tutorial should create conditions for this feeling:

• Tie together purpose and action
• Create smooth flow from step to step
• Allow repetition (learners will repeat successful steps for pleasure)
• Build rhythm and pace

8. Ignore Options and Alternatives

There may be many ways to accomplish something. Ignore all but one. Your job is to guide the learner to a successful conclusion by the most direct path.

Different options can be explored later. Right now, stay focused on what's required to complete the lesson.

9. Perfect Reliability

This is your aspiration. Every step must work, every time, for every user.

In practice, you'll discover problems only through extensive user testing. But the goal is clear: if a learner follows your directions and doesn't get the expected result, they'll lose confidence in the tutorial, the product, and themselves.

You cannot be there to rescue them when things go wrong. The tutorial must rescue itself.

Tutorial Examples

Good tutorial structure:

# Build Your First API Endpoint

In this tutorial, we'll create a simple REST API endpoint that returns user data.
By the end, you'll have a working API you can test in your browser.

## Step 1: Create the endpoint file

Create a new file called `api/users.py` with the following content:

[exact code]

Notice that we're importing the FastAPI library at the top...

## Step 2: Start the server

Run this command in your terminal:

uvicorn api.users:app --reload

You should see output like this:

INFO: Started server process [12345] INFO: Waiting for application startup. INFO: Application startup complete. INFO: Uvicorn running on http://127.0.0.1:8000

The server is now running and will automatically reload when you make changes.

## Step 3: Test your endpoint
...

Bad tutorial (too much explanation, no clear path):

# Understanding REST APIs

REST APIs are a way to build web services. There are several approaches
you could take, including FastAPI, Flask, or Django Rest Framework. Each
has trade-offs in terms of performance and features.

To create an API, you'll need to understand HTTP methods, status codes,
and JSON serialisation...

[More explanation without clear steps]

---

How-to Guides: Goal-Oriented Documentation

What How-to Guides Are

A how-to guide addresses a real-world goal or problem by providing practical directions to help a competent user get their work done.

Key distinction from tutorials: How-to guides serve work, not study. They're for the already-competent user who knows what they want to achieve.

Detailed Principles

1. Address Real-World Problems

Focus on what users need to accomplish, not what the tool can do.

Wrong approach (tool-focused):

• "How to use the deploy command"
• "How to configure database options"

Right approach (problem-focused):

• "How to deploy with zero downtime"
• "How to optimise database performance for high traffic"

The guide should answer: "How do I accomplish [meaningful goal]?"

2. Assume Competence

Your reader:

• Knows what they want to achieve
• Understands the domain
• Can follow directions correctly
• Will adapt your guidance to their specific situation

Don't teach basics. Don't explain concepts. If they need that, they should start with tutorials.

3. Seek Flow

This is critical. Flow means the guide moves smoothly through the user's work.

Ask yourself:

• What must the user hold in their mind right now?
• When can they resolve those thoughts?
• How long are you asking them to keep concerns open?
• What will they reach for next?

Minimise context switching:

• Group operations by tool or location
• Don't make them jump back and forth between files
• Consider the pace and rhythm of their work

At its best, a how-to guide anticipates the user - it places the next tool they need right in their hand.

4. Address Real-World Complexity

Real problems aren't linear. Use conditional imperatives:

• "If you need to limit requests per user, add..."
• "To handle the case where X, do Y"
• "For production deployments, also configure..."

The guide must be adaptable. You can't address every case, so find ways to remain open to possibilities while providing concrete guidance.

5. Omit the Unnecessary

Practical usability beats completeness.

• Start at a reasonable point (not always from scratch)
• End at a reasonable point (not necessarily with everything configured)
• Let the user connect your guidance to their situation
• Don't list every possible option (link to reference instead)

This keeps guides crisp and focused on getting work done.

6. Focus on Tasks, Not Tools

Guides are about human projects and goals. Tools are means to an end.

Sometimes a task aligns closely with one tool, and the guide will concentrate on that tool. Just as often, a real-world task cuts across multiple tools, joining them up in service of the user's goal.

The task defines what the guide covers, not the tool's capabilities.

7. Provide Logical Sequence

Steps should flow in an order that makes sense for human thinking and action, not just technical requirements.

Sometimes the order is imposed by dependencies (step 2 requires step 1). But often there's subtlety: maybe two operations could be done in either order, but one sets up the user's environment or thinking in a way that benefits the other.

Pay attention to sense and meaning in ordering - how human beings think and act.

8. Name Guides Clearly

Titles should say exactly what the guide shows.

Good:

• "How to integrate application performance monitoring"
• "How to configure automated backups"
• "How to troubleshoot deployment failures"

Bad:

• "Performance monitoring" (what about it?)
• "Backups" (too vague)
• "Deployment" (is this how-to or reference?)

Search engines appreciate good titles as much as humans do.

How-to Guide Examples

Good how-to guide:

# How to Configure Rate Limiting

This guide shows you how to add rate limiting to your API endpoints to prevent
abuse and ensure fair usage.

## Basic rate limiting per user

Add the `@rate_limit` decorator to your endpoint:

@app.get("/api/data") @rate_limit(max_requests=100, window=3600) def get_data(): ...

This limits each user to 100 requests per hour.

## Custom limits for different endpoints

If you need different limits for different endpoints, configure them separately:

[specific instructions]

## Handling rate limit errors

When a user exceeds their limit, they'll receive a 429 status code. To customise
the error response:

[specific instructions]

For a complete list of rate limiting options, see the rate limiting reference.

Bad how-to guide (teaching instead of guiding work):

# Rate Limiting

Rate limiting is an important concept in API design. It helps protect your
servers from being overwhelmed and ensures fair resource distribution.

Let's learn about rate limiting by building a simple example. First, we need
to understand how rate limiting algorithms work...

[More explanation than action]

---

Reference: Information-Oriented Documentation

What Reference Is

Reference contains the technical description - facts - that a user needs to do things correctly. It's information you consult while working.

Key characteristic: Reference is neutral. It's not concerned with what the user is doing, only with accurately describing what is.

Detailed Principles

1. Describe and Only Describe

Neutral description is the imperative of reference.

This is harder than it seems. What's natural is to explain, instruct, discuss, opine. These all run counter to reference, which demands accuracy, precision, completeness, and clarity.

Just describe:

• What the thing is
• What it does
• How it behaves
• What options it has
• What constraints apply

Don't explain why it's designed that way (that's explanation). Don't instruct how to use it for a task (that's how-to).

2. Structure Mirrors the Product

The way a map corresponds to territory helps us use it to navigate. Documentation should mirror the product structure.

If a method belongs to a class in a module:

docs/
  reference/
    mymodule/
      MyClass/
        my_method()

This helps users find what they need because the documentation structure matches their mental model of the product.

3. Consistency is Paramount

Use standard patterns throughout. Reference is useful when it's consistent.

For every function, document in the same order: 1. Brief description 2. Parameters 3. Return value 4. Exceptions 5. Example (optional)

For every class: 1. Brief description 2. Constructor 3. Methods 4. Properties

Users should always find information where they expect it, in familiar formats.

4. Be Austere and Authoritative

Reference should be:

• Austere: No decoration, no enthusiasm, no marketing
• Authoritative: No doubt or ambiguity
• Factual: Just what is true

One consults reference, one doesn't read it. It should support quick, confident lookup.

5. Completeness Matters

Unlike how-to guides (which can be selective), reference should be complete.

Document:

• All parameters
• All return values
• All exceptions
• All constraints
• All warnings

Users come to reference for truth and certainty. Incomplete reference undermines confidence.

6. Provide Examples

Examples illustrate without instruction or explanation.

A succinct usage example shows the function in context:

# Authenticate a user
token = User.authenticate(username="alice", password="secret123")

This shows typical usage without falling into "how to authenticate" territory.

Reference Examples

Good reference:

# authenticate()

Authenticates a user with provided credentials and returns an authentication token.

## Parameters

- `username` (string, required): The user's username
- `password` (string, required): The user's password
- `remember` (boolean, optional): Whether to create a persistent session. Default: false
- `timeout` (integer, optional): Session timeout in seconds. Default: 3600

## Returns

`AuthToken` object containing:
- `token` (string): The authentication token
- `expires_at` (datetime): Token expiration timestamp
- `user_id` (integer): Authenticated user's ID

Returns `None` if authentication fails.

## Raises

- `InvalidCredentialsError`: When username or password is incorrect
- `AccountLockedError`: When account is locked due to failed attempts
- `DatabaseError`: When unable to access user database

## Example

token = User.authenticate( username="alice", password="secret123", remember=True )

## Notes

- Passwords are compared using constant-time comparison to prevent timing attacks
- Failed attempts are logged for security monitoring
- Maximum session timeout is 86400 seconds (24 hours)

Bad reference (instructing and explaining):

# authenticate()

This function helps you authenticate users. You should use it when you need to
verify user credentials and create sessions.

The way it works is by checking the password hash against the stored hash in
the database. This is more secure than storing passwords in plain text.

To use it, first make sure you have a user object...

[More instruction than description]

---

Explanation: Understanding-Oriented Documentation

What Explanation Is

Explanation provides context and background. It helps users understand and see the bigger picture.

Key characteristic: Explanation permits reflection. It serves study (like tutorials), but through theoretical knowledge (like reference).

Detailed Principles

1. Talk About the Subject

Explanation approaches topics from multiple directions. It circles around the subject, providing different perspectives.

You're not documenting for action (like tutorials or how-to guides). You're documenting to illuminate understanding.

Even titles should reflect this: "About user authentication", "About database connection policies".

2. Answer "Why"

Explanation is uniquely positioned to address "why" questions:

• Why is it designed this way?
• Why choose this over alternatives?
• Why did this evolve historically?
• Why does this constraint exist?

These questions have no place in tutorials, how-to guides, or reference. Explanation is where they belong.

3. Make Connections

Help weave a web of understanding:

• Connect to related concepts
• Show how parts interact
• Link to things outside the immediate topic
• Draw parallels to familiar ideas

Understanding means seeing relationships. Explanation makes those relationships visible.

4. Provide Context

Give background that helps users understand:

• Historical context: How did we get here?
• Design context: What constraints shaped this?
• Technical context: What trade-offs were made?
• Social context: How do others approach this?

Context transforms isolated facts into meaningful understanding.

5. Permit Opinion and Perspective

Unlike reference (which must be neutral), explanation can and should include:

• Opinions about approaches
• Discussion of trade-offs
• Counter-examples
• Alternative perspectives

Understanding is richer than pure facts. Discussion can consider and weigh contrary opinions.

But keep it bounded - don't let opinion turn into advocacy or marketing.

6. Keep Boundaries Clear

The risk with explanation is that it tends to absorb other things. You feel the urge to include instruction or reference.

But those have their own places. Keep explanation focused on understanding. If you need to instruct, link to a how-to guide. If you need technical details, link to reference.

7. Take a Higher Perspective

Explanation doesn't take the user's eye-level view (like how-to guides) or the close-up view of machinery (like reference).

Its scope is a topic - "an area of knowledge" with reasonable boundaries. It looks at things from above and across, showing the bigger picture.

Explanation Examples

Good explanation:

# About Authentication Strategies

Our authentication system uses JWT tokens rather than session cookies. This decision
reflects several trade-offs in our architecture.

## Session-based vs Token-based Authentication

Session-based authentication stores state on the server. This simplifies some security
concerns - invalidating a session is just deleting a server-side record. However, it
complicates horizontal scaling. Every server needs access to session state, requiring
either sticky sessions (which limit load balancing) or a shared session store (which
becomes a single point of failure).

JWT tokens are stateless. The token itself contains all authentication information,
cryptographically signed. This makes them ideal for distributed systems - any server
can validate any token without coordinating with others.

## The Token Revocation Problem

Stateless tokens create a challenge: how do you revoke a token before it expires?
With sessions, you delete the session record. With JWTs, the token remains valid
until expiration regardless of server-side actions.

We address this through short token lifetimes (15 minutes) combined with refresh
tokens. This limits the exposure window while allowing long-lived sessions. It's a
compromise between security and user experience.

Some teams maintain a token blocklist, but this partially defeats the stateless
benefit and introduces the coordination problem we were trying to avoid.

## Historical Context

We initially used session-based authentication. As we moved to a microservices
architecture with multiple API gateways, session management became increasingly
complex. The shift to JWTs in version 2.0 was driven by these scaling requirements.

For more on implementing JWT authentication, see the authentication how-to guide.
For JWT token reference, see the security reference.

Bad explanation (too much instruction):

# JWT Authentication

To implement JWT authentication, first install the JWT library:

pip install pyjwt

Then create a token like this:

[Code instructions continue...]

This should be in a how-to guide, not explanation.

Additional Guidance and Reference

This file contains the quality framework, guidance for complex scenarios, limitations, and other reference material for applying Diataxis.

Understanding Quality in Documentation

Documentation has two distinct kinds of quality:

Functional Quality (Objective, Measurable)

These characteristics are independent of each other:

• Accuracy: Documentation matches reality
• Completeness: Covers everything it should
• Consistency: No contradictions
• Precision: Clear and unambiguous
• Usefulness: Serves actual needs

Documentation can be accurate but incomplete, or complete but inconsistent. Each is a constraint you must meet through diligence and domain knowledge.

Diataxis cannot give you functional quality. It requires technical skill and keeping documentation synchronised with the product.

However, Diataxis can expose lapses in functional quality:

• Structuring reference to mirror code makes gaps obvious
• Moving explanation out of tutorials highlights unclear steps
• Separating concerns reveals inconsistencies

Deep Quality (Subjective, Felt)

These characteristics are interdependent - aspects of the same thing:

• Feels good to use
• Has flow
• Fits human needs
• Anticipates the user
• Feels beautiful (yes, this matters)

You can't measure these with numbers, only recognise them through use. Like clothing that moves well with your body, good documentation feels right when you use it.

Deep quality is conditional on functional quality. No one experiences documentation as beautiful if it's inaccurate or inconsistent. Lapses in functional quality tarnish the experience immediately.

Diataxis addresses deep quality. It creates conditions where flow, anticipation, and "fits my needs" become possible. It won't make your documentation accurate (that's on you), but it can make accurate documentation feel right to use.

How They Relate

Think of it this way:

• Functional quality = Constraints you must conform to
• Deep quality = Liberation, creativity, taste

Functional quality is a burden - tests you might fail. Deep quality is the pleasure of crafting something that works well.

Diataxis helps pursue deep quality, which makes functional quality lapses more visible, which helps you improve functional quality, which then allows deep quality to shine.

Handling Complex Scenarios

Diataxis is an Approach, Not a Template

Diataxis isn't four boxes to fill. It's a way of thinking about documentation that identifies four needs and uses them to author and structure content effectively.

Real documentation often faces complexity that doesn't fit neatly into simple structures. That's fine. Let documentation be as complex as it needs to be, as long as it's logical and serves user needs.

Multiple User Types

Your product might serve:

• End users who consume the product
• Developers who build on top of it
• Contributors who maintain it

These are effectively different products for different people. Each group has its own relationship with the product.

Think user-first:

• Do developers need to understand user concerns first?
• If yes: Let developer tutorials follow user tutorials
• Do contributors need distinct workflows?
• If yes: Completely separate their how-to guides
• Does each group need all four documentation types?
• Maybe not - provide what each actually needs

Don't force these into rigid structure. Structure follows user needs, not diagram purity.

Multiple Environments or Platforms

Deploying to AWS vs Azure vs on-premise might create vastly different workflows. Same product, different concerns.

Options:

• Separate documentation by environment if experiences differ significantly
• Use common structure where concerns overlap
• Let users find their path based on their situation
• Consider a routing page that directs to environment-specific docs

Complex Hierarchies and Navigation

Real documentation gets large. Some practical guidelines:

Landing Pages

Landing pages should read like overviews, not just present lists.

Provide headings and introductory text that gives context:

## How-to Guides

These guides help you accomplish common tasks with the platform.

### Installation Guides

Choose the installation approach that matches your environment.
Each guide takes about 15 minutes to complete.

- Local installation
- Docker deployment
- Virtual machine setup
- Linux container configuration

### Deployment and Scaling

Once installed, these guides help you deploy and scale your application
for production use.

- Deploy an instance
- Configure load balancing
- Scale your application

List Length

Lists longer than 7 items are hard for humans to read unless they have mechanical order (alphabetical, numerical).

If a section has 15 how-to guides, group them into categories with their own sub-landing pages:

• Installation (4 guides)
• Configuration (5 guides)
• Deployment (6 guides)

Structure Depth

Keep references one level deep from SKILL.md when possible. Don't create deeply nested structures that are hard to navigate or understand.

When Multiple Dimensions Collide

Sometimes you have:

• Four documentation types (tutorials/how-to/reference/explanation)
• AND user types (users/developers/contributors)
• AND environments (cloud/on-premise/hybrid)

Which dimension comes first in hierarchy?

There's no single answer. Think about:

• How do your users think about the product?
• Does a cloud user also need on-premise docs?
• Does a developer typically need all four doc types for their domain?
• What's the most common path users take?

Structure to serve users, not to satisfy a diagram.

What Diataxis Cannot Do

Be clear about the limits:

It Won't Make Your Documentation Accurate

Accuracy requires domain knowledge and keeping docs synchronised with reality. Diataxis can help expose gaps, but can't fill them.

You need to:

• Understand the product deeply
• Test every claim
• Update docs when the product changes
• Verify technical details

It Won't Guarantee Deep Quality

Diataxis creates conditions where flow and anticipation become possible, but it's not a formula.

You still need:

• Taste and judgement
• Understanding of user experience
• Empathy for your users
• Writing skill

It Can't Bypass Other Expertise

Other disciplines matter:

• UX design
• Visual design
• Information architecture
• Technical writing
• Domain expertise

Diataxis complements these, doesn't replace them.

It's Not a Shortcut

Good documentation requires:

• Skill
• Time
• Iteration
• User testing
• Ongoing maintenance

Diataxis provides direction and principles, not magic.

It Won't Solve Every Documentation Problem

Some problems are about:

• Resources and staffing
• Organisational politics
• Product complexity
• Rapidly changing systems
• Technical debt

Diataxis helps with form and structure, not everything else.

Think of Diataxis as laying foundations. Strong foundations create the possibility of excellent documentation, but you still have to build the house.

The User's Journey

Users move through a cycle with your product:

1. Learning phase - Diving in to do things under guidance (tutorials) 2. Goal phase - Putting skills to work on real problems (how-to guides) 3. Information phase - Consulting facts while working (reference) 4. Understanding phase - Stepping back to reflect and deepen knowledge (explanation)

This isn't strictly linear. A user might:

• Jump to reference while following a tutorial
• Return to tutorials when learning new features
• Start with explanation to get oriented
• Skip tutorials entirely if already competent

But there's a natural progression as someone moves from newcomer to expert. Documentation should serve users wherever they are in this cycle.

The Iterative Philosophy

Start Small

Don't try to understand everything about Diataxis before using it. Pick up one idea that seems useful and apply it right now. Understanding comes through practice.

Organic Growth

Think of documentation like a plant:

• A plant is never finished, but always complete at its current stage
• It grows from the inside out, cell by cell
• Structure emerges naturally from healthy development
• It adapts to external conditions

Your documentation should be the same:

• Always complete for its current state
• Always ready to grow further
• Structure emerges from well-formed content
• Adapts to changing user needs

The Basic Workflow

1. Choose something - Any piece, even at random 2. Assess it - Challenge it with Diataxis questions 3. Decide on one action - What single improvement helps now? 4. Do it - Complete that action, commit it 5. Repeat - Go back to step 1

This keeps work flowing without requiring a big plan. Each small change moves in the right direction. Structure forms itself.

Common Boundary Problems

Tutorial/How-to Confusion

This is the most common mistake. The distinction matters because:

Tutorials (at study):

• For learners building competence
• Carefully managed path
• Eliminates the unexpected
• No choices or alternatives
• Concrete and specific
• Teacher takes responsibility
• Can be basic or advanced

How-to Guides (at work):

• For competent users solving problems
• Adapts to real-world complexity
• Prepares for the unexpected
• Offers conditional guidance
• General and adaptable
• User has responsibility
• Can be basic or advanced

The difference isn't basic vs advanced. It's study vs work, learning vs applying.

Medical analogy: A medical school lesson on suturing (tutorial) vs a surgical manual for appendectomy (how-to). Both are professional-level, but one teaches skills, the other guides application of skills.

Reference/Explanation Blur

Reference (work):

• Describes what is
• Boring and unmemorable
• Lists and tables
• You consult it while working
• Neutral facts only

Explanation (study):

• Discusses why and how
• You might read it away from work
• Can be read "in the bath"
• Context and connections
• Can include opinion

The test: Is this something someone would turn to while working (reference) or while reflecting away from work (explanation)?

Additional Patterns

Documentation for Different Maturity Levels

You might have:

• Getting started tutorial (beginners)
• Advanced integration tutorial (experienced developers)
• Basic how-to guides (common tasks)
• Advanced how-to guides (complex scenarios)

This is fine. The tutorial/how-to distinction is about study vs work, not basic vs advanced.

Living Documentation

Documentation that:

• Changes frequently with the product
• Has many contributors
• Serves rapidly evolving needs

Diataxis helps here by:

• Providing clear categories for contributions
• Making it obvious where new content belongs
• Preventing muddle that accumulates over time

Minimalist Documentation

You don't need all four types for every feature. Sometimes you only need:

• Reference (for simple, well-understood tools)
• How-to guide + reference (for established practices)
• Tutorial + reference (for new or complex features)

Provide what users actually need, not what feels complete.

Practical Tips

When Writing

For tutorials:

• Test with real users repeatedly
• Watch where they get stuck
• Fix every point of failure
• Aim for perfect reliability

For how-to guides:

• Talk to users about their goals
• Identify real problems they face
• Focus on flow and anticipation
• Don't try to be exhaustive

For reference:

• Mirror the product structure exactly
• Use automated generation where possible
• Keep it synchronised with code
• Be consistent above all

For explanation:

• Write when you have time to think
• Take multiple perspectives
• Connect to other knowledge
• Don't rush it

When Reviewing

Look for these signs:

Boundary violations:

• Explanation in tutorials (extract and link)
• Instruction in reference (move to how-to)
• Teaching in how-to guides (assume competence)
• Reference detail in tutorials (link instead)

Missing flow:

• Excessive context switching
• Concerns left unresolved
• Unexpected jumps
• Disrupted rhythm

Wrong audience:

• Tutorial assuming competence
• How-to guide teaching basics
• Reference assuming intent
• Explanation instructing

When Stuck

1. Use the compass 2. Read principles for that type 3. Look at examples 4. Ask: What does the user need right now? 5. Serve that need directly

When in doubt, make it simpler and more focused.