divio-documentation

Write Divio Documentation

Writes or reviews documentation following the Divio/Diátaxis four-type system, ensuring each document serves its intended audience and purpose without mixing concerns.

Prerequisites

• The subject to document or the document to review provided in context
• Clarity on which documentation type is needed (or ask to determine it)
• Target audience's knowledge level

Decision Framework

Identify the type before writing:

Is the user studying or working?
        /              \
   Studying           Working
      |                   |
      v                   v
Is it practical    Is it practical
or theoretical?    or theoretical?
  /      \           /      \
Pract.  Theor.    Pract.  Theor.
  |       |         |       |
  v       v         v       v
Tutorial Expl.  How-to   Ref.

Quick identification:

• "I want to learn X" -> Tutorial
• "I want to accomplish Y" -> How-to
• "What are the parameters of Z?" -> Reference
• "Why does X work this way?" -> Explanation

The Four Documentation Types

1. TUTORIALS (Learning-Oriented)

Purpose: Take a complete beginner through steps to complete a meaningful project and gain confidence.

Audience: Absolute beginners with minimal prior knowledge.

DO:

• Start from zero, make no assumptions about prior knowledge
• Provide concrete, specific steps that are reliably repeatable
• Make every step produce a visible, comprehensible result
• Keep the learner moving forward at all times
• End each section with a meaningful accomplishment

DON'T:

• Explain concepts or theory in depth (link to Explanation instead)
• Provide options or alternatives (one clear path only)
• Allow the learner to encounter errors or confusion
• Discuss edge cases or advanced features

Structure:

# Tutorial: [Specific Achievement]

## What You'll Build
## Prerequisites
## Step 1: [Action Verb + Specific Task]
## Step 2: [Next Action]
## What You've Learned
## Next Steps