How-Tos

Disclaimer: This page contains my personal reading notes on the Diátaxis documentation framework.

What this notes cover &#xNAN;My learning notes about how-to guides in the Diátaxis documentation framework.

Overview

A definition from the Diátaxis framework official page:

“How-to guides are directions that take the reader through the steps required to solve a real-world problem. How-to guides are goal-oriented.”

How-to guides are practical documents that are designed and written with a “user at work” in mind assuming that the user has some previous knowledge about the task to complete.

Characteristics

How-to guides have the following characteristics:

• Assume users have some previous knowledge about the task to complete.

• Lead users to complete real-world specific tasks successfully.

• Disclose all the required steps in sequence, addressing key scenarios.

• Provide (if necessary) useful information to prepare users for the unexpected within the context of the task.

Real-world Actions

How-to guides seek users’ success. They provide structured steps to offer a safe path for users to move in a real-world scenario. However, the real world is unpredictable, and there may be specific situations or contexts that fall outside the key scenarios or that are still unknown.

How-to guides "might account for different versions of an operating system, the most common package managers, and a standard set of user permissions". However, How-to guides will not cover specific details of users’ personal work environment configuration or the company’s security policies that manage resource access, installation, or execution.

How-to guides presume users already possess enough knowledge to handle unexpected situations in a given context, for a sequence of steps, related to the technologies being used. This knowledge is not limited to technical or task-related knowledge but also includes an understanding of their work environment.

This is why, when following a how-to guide, users are responsible for addressing unexpected situations.