# How-Tos

> **What this notes cover**\
> \&#xNAN;*My learning notes about how-to guides in the* [*Diátaxis*](https://diataxis.fr/) *documentation framework.*

## Overview

A definition from the [*Diátaxis*](https://diataxis.fr/) 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.