Skip to content

Latest commit

 

History

History
141 lines (117 loc) · 5.31 KB

foo.md

File metadata and controls

141 lines (117 loc) · 5.31 KB

Diátaxis Documentation Framework

Core Concept

The fundamental idea behind Diátaxis is that documentation needs fall into four distinct categories. Each category serves a different purpose and requires a different approach to writing. The framework is not just a list of types, but a systematic way to think about documentation.

The Four Documentation Types

1. Tutorials

  • Definition: A tutorial is a lesson that guides a learner through a practical experience
  • Core Purpose: Skills acquisition through doing
  • Key Attributes:
    • Always practical - the user must do something
    • Designed around a specific learning experience
    • Instructor takes responsibility for learner's success
    • Learning happens through action, not through being taught
  • Special Challenge: The instructor must be "present" through written instruction alone
  • What to Avoid:
    • Don't explain concepts in depth - link to explanations instead
    • Don't assume prior knowledge
    • Don't focus on options or alternatives
    • Don't include reference material
    • Don't show all possible ways to do something
  • Example: Like a driving lesson - the goal is developing skills and confidence, not reaching a destination

2. How-to Guides

  • Definition: Step-by-step guidance to achieve a specific goal
  • Core Purpose: Practical problem solving
  • Key Attributes:
    • Addresses a specific real-world task or problem
    • Written for users who know what they need to do
    • Focused on completing work rather than learning
    • Assumes necessary competence
  • What to Avoid:
    • Don't teach basic concepts
    • Don't explain why things work
    • Don't cover every possible variation
    • Don't include detailed technical specifications
    • Don't focus on learning objectives
  • Examples:
    • "How to store cellulose nitrate film"
    • "How to configure frame profiling"
    • "Troubleshooting deployment problems"

3. Reference

  • Definition: Technical descriptions of the machinery
  • Core Purpose: Information
  • Key Attributes:
    • Contains pure technical facts
    • Must be accurate and complete
    • Structure mirrors the code/system architecture
    • Neutral and objective - like a map
    • Serves users who know what they're looking for
  • What to Avoid:
    • Don't include tutorials or guides
    • Don't explain concepts
    • Don't include opinions or recommendations
    • Don't provide step-by-step instructions
    • Don't teach or guide the reader
    • Don't include best practices
  • Distinction: Like a map that could be used by both a navigator plotting a course or a magistrate in a legal case

4. Explanation

  • Definition: Discussion that clarifies and illuminates a particular topic
  • Core Purpose: Understanding
  • Key Attributes:
    • Provides background and context
    • Can take different approaches to a topic
    • May include opinions and alternative views
    • Connects different concepts
    • Answers "why" questions
  • What to Avoid:
    • Don't include practical steps
    • Don't mix with tutorials
    • Don't focus on specific tasks
    • Don't include detailed technical specifications
    • Don't try to be completely objective
    • Don't include best practices
  • Important Note: Should be separated from tutorials to avoid overloading learners

The Diátaxis Map

The documentation types are arranged along two axes:

Axis Practical Theoretical
Learning Tutorials Explanation
Work How-to Guides Reference

This creates natural tensions and relationships:

  • Tutorials ↔ How-to guides (practical knowledge)
  • Reference ↔ Explanation (theoretical knowledge)
  • Tutorials ↔ Explanation (learning-oriented)
  • How-to guides ↔ Reference (work-oriented)

The Diátaxis Compass

Use this tool to identify documentation types:

If content... ...and serves the user's... Then it belongs in...
Guides action Learning Tutorials
Guides action Work How-to guides
Explains theory Work Reference
Explains theory Learning Explanation

Practical Application

The workflow is intentionally simple:

  1. Look at your current documentation
  2. Ask: "How could this be better?"
  3. Choose ONE small improvement
  4. Make that improvement
  5. Repeat

Key Principles

  1. Separation of Concerns

    • Keep the four types distinct
    • Don't mix tutorials with explanation
    • Link between types instead of combining them

  2. Minimal Approach

    • Start with small improvements
    • You don't need to read or understand everything
    • Each improvement suggests the next

  3. Pragmatic Usage

    • Use what works for you
    • No need to commit to the entire framework
    • Even small improvements are valuable

Important Notes

  • The framework is a practical tool, not a theoretical construct
  • You don't need to understand all of Diátaxis to start using it
  • The documentation will naturally evolve as you make improvements
  • Let real documentation problems guide your use of the framework

[Source: Diátaxis Documentation Framework]