How-to#

Diataxis How-to

Summary#

How-to guides are goal-oriented directions, much like a recipe. They take the reader through the steps required to solve a real-world problem.

Examples could be calibrating a temperature sensor, using fixtures in pytest, and configuring a software package.

Building a web application is not addressing a specific goal or problem. It’s a vastly open-ended sphere of skill that is not a how-to.

Tutorials -> How-to Guides#

How-to guides and Tutorials can easily overlap. However, How-to guides serve a different purpose to tutorials.

See the table below indicating the difference in the user’s needs as they move right along the learning path.

Tutorials -> How-to Guides#

Tutorials: for a Learner

How-to: for a User

May not know the right question.

Responsible for the right question.

Knowlege required is determined by the author.

Knowlege required is determined by the user.

Learner needs to be lead along the path.

User can choose their own path.

Learner aquires knowlege.

User applys knowlege.

Learner needs to be taught.

User needs to be shown.

Often How-to’s are better written than tutorials because they share the same focus as the developer.

The developer has moved past the learning stage, and a How-to is usually the focus of developers documentation.

Its a Recipe#

Recipes are an excellent model for writing a how-to guide.

Recipes clearly define the goal by following it, and they address a specific question: How do I make it?

Following a recipe requires basic competence; a recipe is not a substitute for a cooking lesson.

Reading about the history of a recipe may be exciting, but it doesn’t help achieve the goal of the recipe.

The history of a recipe will provide the user with better value as they move right in the learning path towards the “discussion” phase.

Recipes follow a well-established format; similarly, How-to guides should also follow a format suitable for the technology.

For consistent formatting, The How-to guide could be in the form of a customisable template.

How-to write a How-to#

How-to guides contain a sequence of actions much like a tutorial.

They differ in a sense; a tutorial mentions that “We are using HTTPS” because it is very secure, whereas a How-to guide digs deeper into HTTPS, that is, it shows you how to do a specific action or configuration with HTTPS.

How-to guides don’t need the repeatability of a tutorial, but they should be reliable.

Solving a Problem

The goal of a how-to is to solve a problem or complete an unfamiliar task.

Maintaining that focus throughout the how-to removes the mistake of bringing in “discussion” topics, which unnecessarily increase cognitive load.

No explanation needed

Explanations aren’t necessary when following a how-to guide. Adding descriptions is adding noise on the way to the goal.

Nice and flexible

How-to guides should be flexible and adaptable to many use cases, unlike a particular tutorial to a narrow topic.

Nothing unnecessary

Completeness is not a requirement of a how-to, whereas being practical and useable is.

How-to guides should start and end in a meaningful place and require the reader to apply it to their work.

What is in a name

Explicit is better than ambiguous when naming a how-to guide.

An explicit How-to name:

How to integrate application performance monitoring using XYZ.

It is clear what this how-to describes.

An ambiguous How-to name:

Integrating application performance monitoring.

Perhaps this document is about the question of deciding whether you should Integrate application performance or not, or something entirely different.

A terrible How-to name:

Application performance monitoring.

This name is very general and does not suggest a how-to guide. Perhaps it’s a book title.


Note

Search engines make use of good document names.

Further Reading#

For further interesting reading on this topic, see Diátaxis How-to