Skip to content

Howtos overview


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.


  • to show how to solve a specific problem/question
  • to help the already-competent user perform a particular task correctly


A series of steps.


Not teaching someone how to cook, but follow a recipe in a cookery book.

My responsability

Stick to the practical goal.


  • 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