Howtos overview
What?
How-to guides are directions that take you, the reader, through the steps required to solve a real-world problem. They are goal-oriented.
Say what?
You need to be able to accomplish things. Done well, they are the most-read sections of your documentation.
What they do
They guide. They demonstrate.
Answers the question
"How do I...?"
Oriented to
Goals. Tasks. They serve the need of the user @work. They put the skill to work, help the user accomplish a task.
Purpose
- to show how to solve a specific problem/question
- to help the already-competent user perform a particular task correctly
Form
A series of steps.
Analogy
Not teaching someone how to cook, but follow a recipe in a cookery book.
My responsability
Stick to the practical goal.
Approach
- I won’t explain concepts/things, but refer to a reference guide for a full list of options
- I'll provide a starting-point that you know how to reach; most likely, you will also be in the middle of something
- the path can’t be managed: it’s the real world!
- I'll assume familiarity
- howtos apply to the real world: you will have to deal with what I'll throw at you
- you must prepare for the unexpected
- you wil have to rely on implicit knowledge
- and complete a particular task
- howtos are reliable, but not the cast-iron repeatability of a tutorial, they cannot promise safety
- I'll use conditional imperatives
- and general approaches
- howtos will typically fork and branch, describing different routes to the same destination