How to write clear step-by-step instructions

Writing Clear Step-by-Step Instructions

Bad step-by-step instructions have two failure modes: steps that bundle multiple actions, and steps that omit expected output. Both leave readers unsure whether they're on the right track.

One Action Per Step

Every step should begin with an action verb and contain exactly one action:

• ❌ "Install the dependencies and configure your environment variables, then start the server." (three actions)
• ✅ Step 3: Install dependencies → Step 4: Configure environment variables → Step 5: Start the server

Step Template

## Step 3: Install dependencies

Run the install command in your project root:

```bash
npm install
```

Expected output:
```
added 142 packages in 4.2s
```

If you see `EACCES` permission errors, see [Fixing npm permission errors](#troubleshooting).

Handling Branches

When a step has conditional paths, be explicit:

## Step 4: Configure authentication

**If you're using an API key:**
Set `AUTH_TYPE=apikey` in your `.env` file.

**If you're using OAuth:**
Set `AUTH_TYPE=oauth` and follow the [OAuth setup guide](#).

Never make readers guess which path applies to them. State the condition, then give the step for each case.