How-To Guide Writing — Vocabulary and Structure

How-to guide structure: Goal (what the reader will accomplish), Prerequisites (what they need before starting: access, installed tools, knowledge), Steps (numbered, one action per step, with expected output), Verification (how to confirm success), Troubleshooting (common errors and fixes). Scannable format: headers, numbered steps, code blocks.

Prerequisites save frustration: 'Before you begin: You need Admin access to the AWS console, AWS CLI v2 installed and configured, and the ARN of your S3 bucket.' Readers who don't meet prerequisites find out immediately — not after completing half the steps. Prerequisite clarity is a hallmark of professional technical documentation.

Expected output after each step: 'You should see a message like: Successfully configured AWS profile. If you see an error, see Troubleshooting below.' Expected output lets readers self-check. It transforms a guide from a list of commands into a verifiable procedure — drastically reducing support requests.

Callout hierarchy: Note/Info (additional helpful context), Warning (could cause problems if ignored — e.g., 'This will overwrite existing files'), Danger/Caution (irreversible consequences — e.g., 'This permanently deletes the database'). Visually distinct (icons, colored boxes) so scanners cannot miss them. Critical for runbooks and operations guides.

Audience targeting: 'This guide is for backend engineers setting up their local development environment for the first time. Assumes basic familiarity with the terminal but no prior knowledge of our stack.' This tells readers if the guide is for them and tells writers what to explain vs. what to assume. Without it, guides are written for an imaginary average reader who may not exist.