Why Document Type Matters
One of the most common documentation mistakes is writing the wrong type of document for the reader's need. A developer trying to get started does not need an architectural decision record. An SRE during an incident does not need a tutorial. Choosing the wrong format wastes the reader's time and buries the information they actually need.
The Diátaxis framework (developed by Daniele Procida) provides a clean taxonomy of four documentation types, organized by two axes: whether the reader is studying or working, and whether the content is practical or theoretical.
The Four Document Types
1. Tutorial (Learning-oriented)
A tutorial guides a complete beginner through a hands-on exercise. The goal is not to teach the tool comprehensively — it is to give the reader a successful first experience and build confidence.
- Reader state: Learning, no prior knowledge assumed.
- Structure: Narrative, sequential steps, lots of "you will see..." guidance.
- Example: "Deploy your first application to Kubernetes in 10 minutes."
2. How-To Guide (Task-oriented)
A how-to guide helps a competent user accomplish a specific goal. Unlike a tutorial, it assumes the reader knows the basics and just needs the steps.
- Reader state: Working, knows what they want to do.
- Structure: Numbered steps, minimal explanation, direct commands.
- Example: "How to configure TLS termination on an Nginx ingress."
3. Reference (Information-oriented)
Reference documentation describes the system accurately and completely. It is consulted, not read linearly.
- Reader state: Working, needs to look up a specific fact.
- Structure: Alphabetical or logical grouping, consistent format, no narrative.
- Example: API documentation, CLI flag reference, configuration schema.
4. Explanation (Understanding-oriented)
Explanation documents (also called "conceptual guides" or "ADRs — Architecture Decision Records") discuss why things are the way they are. They provide context, trade-offs, and background.
- Reader state: Studying, wants to understand.
- Structure: Prose, diagrams, discussion of alternatives.
- Example: "Why we chose Kafka over RabbitMQ for our event bus."
Applying the Taxonomy
When you sit down to write, identify which type you are writing before you start. If you find yourself mixing types — explaining history in a how-to guide, or adding step-by-step commands to a conceptual doc — stop and split the document.