Why the Divio Documentation System?
Spec Kitty uses the Divio documentation system to organize its docs. This document explains why we chose this system and how it works.
The Problem with Traditional Documentation
Most documentation suffers from mixed concerns:
Common problems:
- A "quickstart" that's actually a reference manual
- API reference mixed with tutorials
- No clear path for different user needs
- "Everything on one page" syndrome
- Documentation that tries to be everything to everyone
The result:
- Beginners can't find where to start
- Experts can't find the specific information they need
- Writers don't know what to write
- Documentation becomes a dumping ground
The Four Types of Documentation
The Divio system identifies four distinct types of documentation, each serving a different purpose:
1. Tutorials (Learning-Oriented)
Purpose: Teach a beginner through doing.
Characteristics:
- Hands-on, step-by-step instructions
- Complete working examples
- Focuses on learning, not accomplishing
- "Follow along with me"
Spec Kitty example: "Your First Feature with Spec Kitty" - walks through creating a feature from start to finish
2. How-To Guides (Task-Oriented)
Purpose: Help accomplish a specific goal.
Characteristics:
- Assumes basic knowledge
- Goal-oriented ("How to X")
- Practical steps
- Doesn't explain underlying concepts
Spec Kitty example: "How to Review a Work Package" - steps to review, without explaining why review matters
3. Reference (Information-Oriented)
Purpose: Describe the machinery.
Characteristics:
- Technical descriptions
- Accurate and complete
- Structured consistently
- "What it is, not what to do with it"
Spec Kitty example: "CLI Reference" - all commands, flags, and options documented
4. Explanations (Understanding-Oriented)
Purpose: Help understand concepts.
Characteristics:
- Background and context
- Why things work this way
- Alternative approaches considered
- "Understanding, not doing"
Spec Kitty example: This document you're reading right now
The Four Quadrants
PRACTICAL THEORETICAL
↓ ↓
┌───────────────────────────┬───────────────────────────┐
│ │ │
STUDYING │ TUTORIALS │ EXPLANATIONS │
│ (learning-oriented) │ (understanding-oriented) │
│ │ │
│ "Follow along to │ "Why does this work │
│ learn X" │ this way?" │
│ │ │
├───────────────────────────┼───────────────────────────┤
│ │ │
WORKING │ HOW-TO GUIDES │ REFERENCE │
│ (task-oriented) │ (information-oriented) │
│ │ │
│ "Steps to │ "Complete list of │
│ accomplish X" │ all options" │
│ │ │
└───────────────────────────┴───────────────────────────┘
Why This Works
Different users need different things at different times:
| User State | Need | Doc Type |
|---|---|---|
| New to Spec Kitty | Learn the basics | Tutorial |
| Need to do something specific | Practical steps | How-To |
| Looking up a specific flag | Accurate information | Reference |
| Want to understand design decisions | Context and reasoning | Explanation |
The same user might need all four types at different times:
- Day 1: Follow the tutorial
- Week 1: How to handle a specific case
- Week 2: Look up command syntax
- Month 1: Understand why the architecture is this way
How Spec Kitty Uses Divio
Documentation Structure
docs/
├── tutorial/ # Learning-oriented
│ ├── first-feature.md # Your first feature end-to-end
│ ├── working-with-agents.md # Multi-agent basics
│ └── ...
│
├── how-to/ # Task-oriented
│ ├── review-work-package.md # How to review
│ ├── resolve-conflicts.md # How to handle merge conflicts
│ └── ...
│
├── reference/ # Information-oriented
│ ├── cli-reference.md # All commands and flags
│ ├── configuration.md # All config options
│ └── ...
│
└── explanation/ # Understanding-oriented
├── spec-driven-development.md
├── divio-documentation.md # (this file)
├── workspace-per-wp.md
└── ...
Cross-Referencing
Each doc type links to related docs of other types:
- Tutorial links to Reference for full command syntax
- How-To links to Explanation for deeper understanding
- Reference links to How-To for usage examples
- Explanation links to Tutorial for hands-on learning
Writing Guidelines
When writing tutorials:
- Use real examples the user can follow
- Don't explain theory (link to explanations instead)
- Every step should work exactly as shown
When writing how-tos:
- Start with the goal ("How to...")
- Give practical steps
- Don't teach (link to tutorials instead)
When writing reference:
- Be complete and accurate
- Use consistent structure
- Don't include "why" (link to explanations)
When writing explanations:
- Focus on understanding
- Discuss alternatives and trade-offs
- Don't give step-by-step instructions
Common Mistakes to Avoid
Mixing Types
Bad (tutorial mixed with reference):
# Getting Started
Run `spec-kitty init`. This command accepts the following flags:
--force, --quiet, --verbose, --config=PATH, --mission=TYPE...
[100 lines of flag documentation]
Good (tutorial with link to reference):
# Getting Started
Run `spec-kitty init` to set up your project.
For all available options, see the [CLI Reference](../reference/cli-commands.md#spec-kitty-init).
Wrong Type for User State
Bad (explanation when user needs how-to):
# How to Resolve Merge Conflicts
First, let's understand why merge conflicts occur. When Git
encounters changes to the same file from different branches,
it cannot automatically determine which changes to keep...
[500 words of theory]
Good (how-to focused on doing):
# How to Resolve Merge Conflicts
1. Identify conflicting files: `git status`
2. Open each file and find `<<<<<<<` markers
3. Choose which changes to keep
4. Remove conflict markers
5. Stage and commit: `git add . && git commit`
For background on why conflicts occur, see [Git Worktrees Explained](../explanation/git-worktrees.md).
Further Reading
- Divio Documentation System - The original framework
- What nobody tells you about documentation - Conference talk by Divio's creator
See Also
- Spec-Driven Development - The methodology behind Spec Kitty
- Mission System - How different missions produce different documentation
This document explains why we use Divio. For how to write documentation, see the tutorials and how-to guides.