DEV Community

Natália Kováč
Natália Kováč

Posted on

Editing numbered steps so readers never lose their place

Numbered steps look like the easy part of a tutorial. But readers move back and forth between the page and their screen at every step, and that's where they lose their place. A step that hides two actions, or a warning that comes after the click, sends them back to reread.

When I edit a procedure, I read it as someone with one eye on the page and one on the screen. These are the edits I make most often.

One action per step

A step should be one thing the reader does before looking back at the page. When I see "and then" in a step, or two commands, I split it. The list gets longer, but ten short steps are easier to follow than five crowded ones, because the reader always knows which number they're on.

Condition first, then the action

"Click Delete, but only if you've exported your data first" is in the wrong order. By the time the reader reaches the condition, they may have clicked already. I move the condition or context to the front: "If you've exported your data, click Delete." Location works the same way: "In the Settings panel, select Notifications."

Say what the reader should see

Most steps stop at the action. I add a short line saying what should happen: a message appears, a file is created, a new tab opens. That's how readers know the step worked, and how they notice a problem right away instead of several steps later. If the writer isn't sure what the result looks like, nobody has checked.

Commands get their own code block

A command buried in a sentence is hard to copy and easy to mistype. Each command gets its own code block, with the prose before it saying what it does and after it saying what to expect.

Move optional paths out of the steps

"Alternatively, you can..." in the middle of a step forces a decision while the reader is busy following. If there are two real paths, such as cloud and self-hosted, I split them into two procedures or put the choice before step 1. Optional extras go in a note after the last step.

Use the same verb for the same action

Click, hit, tap, choose, pick: when a page mixes them, readers wonder if they mean different things. I agree on a small set, for example click for buttons, select for menu options, enter for typing into a field, press for keys, and match interface labels exactly, in bold.

Before and after

Here's a typical draft:

1. Clone the repository and install the dependencies with `npm install` and then start the server with `npm run dev`.
2. Hit **Save**, or alternatively press Ctrl+S if you prefer, and if you're on the cloud version skip to step 5.
Enter fullscreen mode Exit fullscreen mode

And the same steps after editing. On the real page, the commands would be fenced code blocks; here they're indented so the example stays readable:

1. Clone the repository and open its folder in a terminal.

2. Install the dependencies:

       npm install

   When it finishes, the project has a `node_modules` folder.

3. Start the development server:

       npm run dev

   The terminal shows the local address where the app is running.

4. In the app, click **Save**.

   A "Saved" message appears at the top of the page.
Enter fullscreen mode Exit fullscreen mode

The cloud path from the old step 2 moved out of the list entirely, into its own short section.

A quick check for crowded steps

A small script helps me find steps worth a second look. It flags numbered lines with more than one "and" or more than one inline code span:

import re
import sys

STEP = re.compile(r"^\s*\d+\.\s+(.*)")
CODE = re.compile(r"`[^`]+`")

with open(sys.argv[1], encoding="utf-8") as f:
    for number, line in enumerate(f, start=1):
        match = STEP.match(line)
        if not match:
            continue
        text = match.group(1)
        ands = len(re.findall(r"\band\b", text, re.IGNORECASE))
        commands = len(CODE.findall(text))
        if ands > 1 or commands > 1:
            print(f"line {number}: {ands} x 'and', {commands} code spans")
            print(f"  {text.strip()}")
Enter fullscreen mode Exit fullscreen mode

Save it as check_steps.py and run it with the file name:

python3 check_steps.py tutorial.md
Enter fullscreen mode Exit fullscreen mode

It only reads the first line of each step and can't tell a list of things from two actions, so it points me to places to look, not fixes. On the draft above, it flags step 1.

The last check: follow the steps yourself, looking at the screen after each one. If you have to search the page to find where you were, that step needs another edit.

Top comments (2)

Collapse
 
docsalive profile image
DocsAlive Team •

Putting the condition before the action is such an underrated edit. If you want to catch the 'what should the reader see' lines going stale, it helps to run the procedure from a clean environment (a fresh container or VM) whenever the product changes, and compare the real output with what the doc says. Pasting the exact expected output or message text in a code block also makes it searchable and easier to diff.

Collapse
 
burdettelamar profile image
Burdette Lamar •

Thanks, Natália. Very useful.