When a reader gets stuck at step three of a tutorial, the problem is often not step three. It's the "Before you begin" section, which promised the reader was ready when they weren't. They installed the wrong version, or they don't have the right permission, or the tutorial assumed they knew something it never mentioned.
Prerequisites are usually written last and edited least. I've learned to give them a full editing pass of their own. Here's what I look for.
Vague items that can't be checked
A typical first draft looks like this:
## Prerequisites
- Node.js
- Docker
- A GitHub account
- Basic knowledge of the command line
Every item is true, and almost none helps. Which Node.js version? Does Docker need to be running, or just installed? What does the GitHub account need to be able to do? And "basic knowledge" means something different to every reader.
My test for each item: could a reader find out, in under a minute, whether they meet it? If not, the item needs editing.
Versions: give a number and a way to check
If the tutorial depends on a minimum version, say so, and show the command that prints it:
node --version
If the writer doesn't know the minimum, I ask them to note the version they tested with. "Tested with Node.js 20" is honest and still useful: readers on an older version know where to look first.
Installed is not the same as ready
Some tools can be installed but not usable. Docker is the classic case: the command exists, but the daemon isn't running, and the reader only finds out halfway through. A better check tests the thing the tutorial actually needs:
docker info
If Docker isn't running, this fails straight away with an error about not being able to connect to the daemon. That's much kinder at the top of the page than at step three.
Accounts and permissions
"A GitHub account" hides two questions: is the reader signed in where the tutorial needs them to be, and do they have permission to do what the steps ask? If a step creates a repository in an organisation or adds a secret, the reader needs more than an account.
Where a command exists to check this, I include it. For the GitHub CLI:
gh auth status
For local permissions, on Linux, a reader can check whether they're in the docker group, which is what lets them run Docker without sudo:
groups
When there's no command, I ask the writer to name the role or permission exactly, using the same words the interface uses, so readers can find it in their settings.
Assumed knowledge: name it and link it
"Basic knowledge of the command line" doesn't tell anyone whether they qualify. I replace it with the specific things the tutorial expects readers to do without explanation: change directories, set an environment variable, edit a file in a terminal editor. Then I link one good introduction for readers who need it. They can decide for themselves, and nobody feels tested.
Before and after
Here's the same section after editing:
## Before you begin
You'll need:
- **Node.js 20 or later.** Check with `node --version`.
- **Docker, installed and running.** Run `docker info`. If you
see an error about connecting to the daemon, start Docker first.
- **A GitHub account with permission to create repositories**
in the organisation you'll use. Check you're signed in to the
GitHub CLI with `gh auth status`.
- **Comfort with a few terminal basics:** changing directories,
setting environment variables, and editing a text file.
It's longer. It's also something a reader can work through like a checklist, and each line either passes or tells them what to fix.
Test it from a clean start
The final check isn't an edit at all. I ask someone who didn't write the tutorial to follow the prerequisites on a machine that isn't already set up, or in a fresh container or virtual machine. Writers have everything installed already, so they can't see what's missing. A clean setup shows it in minutes.
When a reader gets stuck now, I check this section first. Most of the time the fix is one more line in it.
Top comments (0)