Diataxis Documentation Organization

Reorganize documentation by classifying content into the four Diataxis quadrants and creating a structured documentation hierarchy.

The Four Quadrants

Quadrant Orientation Purpose User Need

Tutorial Learning Teach through doing "I want to learn"

How-to Task Solve specific problems "I want to accomplish X"

Reference Information Describe the machinery "I need facts about Y"

Explanation Understanding Clarify concepts "I want to understand why"

Step 1: Analyze Existing Documentation

Scan the documentation directory and classify each file or section:

For each document/section, determine:

• Does it walk through steps to learn? → Tutorial
• Does it solve a specific problem? → How-to
• Does it describe APIs/configs/specs? → Reference
• Does it explain concepts/rationale? → Explanation

Step 2: Create Directory Structure

Organize docs into this hierarchy:

docs/ ├── tutorials/ # Learning-oriented │ ├── getting-started/ │ └── {topic}/ ├── how-to/ # Task-oriented │ ├── {task-category}/ │ └── troubleshooting/ ├── reference/ # Information-oriented │ ├── api/ │ ├── configuration/ │ └── architecture/ ├── explanation/ # Understanding-oriented │ ├── concepts/ │ ├── decisions/ │ └── background/ └── README.md # Navigation hub

Step 3: Classification Criteria

Tutorials (Learning)

Characteristics:

• Step-by-step instructions for beginners

• Builds toward a working example

• Focuses on "what the user does"

• Has a concrete end goal

Example titles:

• "Your First Application"

• "Getting Started with X"

• "Building a Sample Project"

DO NOT include:

• Exhaustive options or configurations

• Theoretical explanations

• Edge cases

How-to Guides (Tasks)

Characteristics:

• Assumes basic knowledge

• Addresses a specific problem

• Provides actionable steps

• May have multiple valid approaches

Example titles:

• "How to Deploy to Production"

• "Migrating from v1 to v2"

• "Configuring Authentication"

DO NOT include:

• Teaching fundamentals

• Complete API documentation

• Philosophical discussions

Reference (Information)

Characteristics:

• Accurate and complete

• Consistent structure

• Describes what IS (not how to use)

• Dry, factual tone

Example content:

• API endpoints and parameters

• Configuration options

• CLI commands and flags

• Data schemas

DO NOT include:

• Explanations of why

• Step-by-step tutorials

• Opinions or recommendations

Explanation (Understanding)

Characteristics:

• Discusses context and background

• Explains design decisions

• Connects concepts together

• Can be discursive

Example titles:

• "Understanding the Event Loop"

• "Why We Chose X over Y"

• "Architecture Overview"

DO NOT include:

• How-to instructions

• Reference specifications

• Beginner tutorials

Step 4: Split Mixed Documents

When a document contains multiple types:

• Identify boundaries - Mark where content shifts purpose

• Extract sections - Move each type to its proper location

• Add cross-references - Link related content across quadrants

• Preserve context - Ensure each piece stands alone

Example Split

Before (mixed document):

Authentication

Authentication uses JWT tokens. (explanation)

Quick Start

1. Install the package... (tutorial)

API Reference

• authenticate(user, pass) - Returns token (reference)

Troubleshooting

Token Expired

If you see error X, do Y... (how-to)

After (split):

tutorials/authentication-quickstart.md how-to/troubleshooting/token-expired.md reference/api/authentication.md explanation/concepts/authentication.md

Step 5: Create Navigation Index

Always use README.md as the root navigation file — never index.md .

Build a documentation hub that helps users find content by their need:

Documentation

Learning

New here? Start with our tutorials:

• Getting Started
• Your First App

Guides

Solve specific problems:

• Deployment
• Troubleshooting

Reference

Technical specifications:

• API Reference
• Configuration

Understanding

Deep dives and background:

• Architecture
• Design Decisions

Quality Checklist

After reorganization, verify:

• Each document serves ONE purpose

• Tutorials have clear learning outcomes

• How-to guides solve specific problems

• Reference is complete and accurate

• Explanations provide genuine insight

• Cross-references connect related content

• Navigation makes user intent clear

• No orphaned or duplicated content

Anti-Patterns to Fix

Problem Solution

Tutorial with exhaustive options Move options to reference, link to it

How-to explaining fundamentals Extract to tutorial, assume knowledge

Reference with usage examples Move examples to how-to

Explanation with code snippets Keep only conceptual snippets

One giant README Split into proper quadrants

Output Format

After analysis, report:

Documentation Audit

Current State

• Total documents: X
• Mixed documents: Y
• Missing quadrants: [list]

Classification Results

Proposed Structure

[Directory tree with file placements]

Cross-References Needed

• [doc A] should link to [doc B]
• ...