Note
This is an import from my original notes repository original draft of my notes to quicky help someone get started with the diataxis/divio documentation structure! They’ve been integrated into Denperidge-Redpencil/project.
Divio Docs Quickstart
An attempt at boiling down the amazing 30min talk/documentation on how to write better documentation into something unobtrusive enough for people familiar with it to use as a checklist, but instructive enough for people unfamiliar with it to somewhat do the thing.
Does your documentation include…
Tutorials?
For each tutorial: write as if you’re teaching a child how to cook.
Checklist:
- Holds the readers hand from start to finish
- Gives a sense of achievement
- Works for everyone, with minimal explanation
- Also teaches what you take for granted
How-To guides?
For each how-to: write down how to achieve 1 specific thing as if it were a cooking recipe.
Checklist:
- Only 1 practical goal per how-to
- Minimal explanation
- Flexible: works for different but similar uses
A reference?
For each reference: write as if you are writing an encyclopedia article.
Checklist:
- Structured like the codebase
- Doesn’t explain common tasks (how-to guides)
- Doesn’t explain basic concepts (tutorials)
- Fully describes the machinery
Explanations: discussions/background material?
For each background material: write as if you’re writing about the history and context of a subject.
Checklist:
- Explains design decisions
- Considers alternatives
- Helps the reader make sense of things