A lot of documentation is technically correct and still hard to use. The information is there, but the reader has to work to get it out. Most of the time the fix isn't a rewrite. It's a handful of small, repeatable edits.
These are the ones I make most often when I edit docs, READMEs and how-to guides.
1. Put the goal before the instruction
Readers scan for the thing they want to do. Make that the first thing they see.
Before:
Run
npm run build -- --analyzeif you want to see which packages make the bundle large.
After:
To see which packages make the bundle large, run
npm run build -- --analyze.
Same words, but the reader can now decide in the first few words whether the sentence is for them.
2. One action per step
Numbered steps that hide three actions in one step are where people get lost.
Before:
- Create a
.envfile, add your API key and restart the server.
After:
- Create a file called
.envin the project root.- Add your API key:
API_KEY=your-key-here- Restart the server.
More steps, but each one is easy to finish and easy to come back to if something goes wrong.
3. Say what success looks like
After an important step, tell the reader what they should see. Otherwise they don't know whether to continue or start debugging.
Run
docker compose up. When the setup works, the last line of the output isServer listening on port 3000.
This one edit removes a lot of "is it supposed to do this?" questions.
4. Put conditions and warnings before the step
If a step only applies in some cases, or can break something, say so before the command, not after it.
Before:
Run
make reset-db. This deletes all local data.
After:
Warning: the next command deletes all local data. Run
make reset-db.
People copy and paste. By the time they read the sentence after the command, it has already run.
5. Define a term the first time, then stick to it
If you call something a "workspace" in one section, a "project" in the next and an "environment" later, readers will assume these are three different things. Pick one word, explain it briefly the first time it appears, and use it consistently. A short glossary helps if the docs use many specialised terms.
6. Cut "simply", "just" and "easy"
"Simply configure the proxy" is fine for the person who already knows how. For everyone else it adds a small sting: if it's simple and I'm stuck, the problem must be me. These words rarely add information, so removing them costs nothing.
A quick way to apply these
When I edit a doc, I do one pass per edit instead of trying to fix everything at once:
- Read only the headings and first sentences. Is the goal always up front?
- Read only the numbered steps. One action each? Success described?
- Search for "simply", "just" and "easy".
- Search for every key term and check it's used the same way.
Each pass is quick, and doing them separately means I actually notice the problems instead of skimming past them.
None of this needs a tool or a style guide. It just needs someone to read the doc as a person who has never seen the project before. If you can, ask a new teammate to follow your guide while you watch. You'll find the confusing step within minutes.
What edits do you find yourself making again and again in docs?
Top comments (1)
Great list. My addition: bold the one thing the reader must not skip in each step. People skim numbered lists at speed, and the bolded command or filename is often the only part they actually read. Your one-action-per-step rule plus a bolded anchor makes a step nearly impossible to mess up.