Related: The Documentation System
Documentation often suck, and not because people have bad intentions to do so or a dearth of effort.
The issue is that there’s actually four categories of software documentation, and as writers we often lump them all together in an amorphous blob of text.1
Four Categories of Documentation
Here’s how one can better think about these four parts (from the website):
| oriented to | must | its form | analogy | |
|---|---|---|---|---|
| Tutorials | learning | allow the newcomer to get started | a lesson | teaching a small child how to cook |
| How-to Guides | a goal | show how to solve a specific problem | a series of steps | a recipe in a cookery book |
| Reference | information | describe the machinery | dry description | a reference encyclopedia article |
| Explanation | understanding | explain | discursive explanation | an article on culinary social history |
What matters in each category
Tutorial
lessons that take the reader by the hand through a series of steps to complete a project
- learning by doing
- getting started
- inspiring confidence
- repeatability
- immediate sense of achievement
- concreteness, not abstraction
- minimum necessary explanation
- no distractions
How-to Guides
guides that take the reader through the steps required to solve a common problem2
- a series of steps
- a focus on the goal
- addressing a specific question
- no unnecessary explanation
- a little flexibility — for the reader to adapt to their specific problem
- practical usability
- good naming
Reference
technical descriptions of the machinery and how to operate it
- structure
- consistency
- description
- accuracy
Explanation
explanations that clarify and illuminate a particular topic
- giving context
- explaining why
- multiple examples, alternative approaches
- making connections
- no instruction or technical description