Pick the Right Doc Type
Why types matter
Every doc in the handbook is exactly one type. The type sets the shape of the doc, the reading mode the reader expects, and which template you start from. Mixing types — half tutorial, half reference — is the number one way docs become unreadable.
Pick the right type
A short decision tree:
- Is the reader learning something new? → Tutorial
- Are they trying to do a task?
- A routine task → How-to
- An incident-response playbook → Runbook
- Are they trying to understand or look up?
- Look up a specific fact → Reference
- Grasp a concept or why something is the way it is → Explanation
- Are you recording a moment in time?
- A decision you made → ADR (Architectural Decision Record)
- An incident that happened → Postmortem
The seven types
| Type | For a reader who... | Example | Template |
|---|---|---|---|
| Tutorial | is learning — needs to be taught | "Build your first API endpoint" | tutorial.md |
| How-to | knows the area, needs a recipe | "Add a new OAuth provider" | how-to.md |
| Runbook | is on-call, fixing a known issue | "Database connection pool exhausted" | runbook.md |
| Reference | is looking up a fact | API endpoint listing | reference.md |
| Explanation | is trying to understand | "How auth tokens work" | explanation.md |
| ADR (Architectural Decision Record) | wants to know why we chose X (frozen) | "Postgres over MongoDB for the user store" | adr.md |
| Postmortem | is reading lessons from an incident (frozen) | "Cache stampede caused 8-minute outage" | postmortem.md |
Append-only types
ADR and Postmortem are append-only. Once published, they don't get edited (not the updates but corrections or extentions might allowed) even if the decision later changes or new evidence emerges. Instead, write a new doc that supersedes the old one. This preserves the historical record: a future reader can see what was known at the time, not just where we ended up.
Adding a doc type
Carefully check the implementation and add it in places needed and do the through test. Don't add slugs preemptively — only when a real type needed.