writing-documentation-with-diataxis

Files (3)

• SKILL.md
• principles.md
• reference.md

SKILL.md (first lines)

# 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:

| Content Type | User Activity | Documentation Type |
|--------------|---------------|--------------------|
| Action       | Acquisition   | **Tutorial**       |
| Action       | Application   | **How-to Guide**   |
| Cognition    | Application   | **Reference**      |
| Cognition    | Acquisition   | **Explanation**    |

## 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

From sammcj/agentic-coding, Apache-2.0.

More from sammcj/agentic-coding