Writing a how-to document

Why it matters

Much of technical work is repeated: setting up a development environment, calibrating an instrument, restarting a service, changing a filter, onboarding a new teammate. When the steps live only in one person's head, the work stops when that person is away, and mistakes creep in. A good how-to document, often called a procedure or SOP (standard operating procedure), lets someone else do the task correctly the first time.

In regulated fields such as clinical labs, manufacturing and utilities, written procedures are required, and people are trained and audited against them. In software teams, the same idea shows up as READMEs, runbooks and setup guides.

The core idea: one action per numbered step

A procedure is a recipe. The reader follows it while doing the task, often with their hands busy and their attention split. So each step should be:

• Numbered, because order matters.
• One action, starting with a verb: "Open", "Enter", "Press", "Wait".
• Specific: exact names, values and units.
• Followed by what the reader should see, so they know it worked.

A simple structure

Most how-to documents can use the same skeleton:

1. Title: what the procedure achieves. "Set up the project on a new laptop", not "Setup notes".
2. Purpose and scope: one or two sentences on when to use it and when not to.
3. Before you start: prerequisites, access, tools, materials and how long it takes.
4. Safety or warnings: anything that could harm a person, data or equipment, placed before the step it applies to.
5. Steps: numbered, one action each, with expected results.
6. Check that it worked: a final test.
7. Troubleshooting: the two or three most common problems and their fixes.
8. Owner and date: who maintains it and when it was last checked.

Worked example

Here is a weak version of a software setup guide:

Install stuff, clone the repo, set up the env file and run it. Ask
Dev if it doesn't work.

And a usable one:

## Run the API on your laptop

Use this to run the API locally for development. It takes about
15 minutes. It does not cover production deploys.

### Before you start
- Node.js 22 installed (check with `node --version`).
- Read access to the GitHub repository.

### Steps
1. Clone the repository:
   ```bash
   git clone git@github.com:example/api.git
   ```
2. Move into the folder: `cd api`
3. Install the dependencies: `npm ci`
   You should see "added ... packages" with no errors.
4. Copy the example settings file: `cp .env.example .env`
5. Start the server: `npm run dev`
   You should see "Listening on port 4000".

### Check that it worked
Open http://localhost:4000/healthz in a browser. It shows `ok`.

### Troubleshooting
- "node: command not found": install Node.js 22, then repeat step 3.
- "Port 4000 is already in use": stop the other process, or set
  PORT=4001 in .env.

Owner: Platform team. Last checked: 2026-10-01.

Notice how the expected results ("You should see...") let the reader catch a problem at the step where it happens, instead of at the end.

The same structure works away from a computer. For example, a procedure for replacing a printer toner cartridge would list the cartridge model under "Before you start", put "Turn off the printer and let the fuser cool for 10 minutes" as an early step with the reason, and end with "Print a test page".

Warnings: put them before the step

A warning placed after the step is read too late. Use clear labels and say what could happen:

CAUTION: The next step erases every record in the test database.
Confirm you are connected to "test", not "production".
6. Run: npm run db:reset

For physical work (machinery, electricity, chemicals), a written procedure does not replace the training and supervision your employer or school must provide. Never write or follow a safety-critical procedure on your own without that.

Test it on someone else

The only real test of a procedure is watching someone else follow it. Give it to a person who has never done the task. Do not help them. Note every place they hesitate, guess or ask a question. Each one is a step to fix. This is sometimes called a "hallway test" or "usability test" for documents.

Common mistakes

• Several actions in one step ("Open the app, log in, go to settings and change the region").
• Missing prerequisites, so the reader gets stuck at step 6.
• Vague words: "set the temperature appropriately", "wait a bit".
• No expected results, so mistakes are only found at the end.
• Out-of-date documents. Add an owner and a "last checked" date, and update the procedure whenever the process changes.

Quick recap

• Title, purpose, prerequisites, warnings, numbered steps, check, troubleshooting, owner.
• One verb-first action per step, with what the reader should see.
• Warnings go before the step they apply to.
• Test the document on someone who has never done the task.

Try it

Open the Do tab. You will write a numbered procedure for a task you know well and test it on another person.