Step-by-Step Clarity: One Action per Step

Tuesday, 07:50, at Larkfield Academy, first day of term. Ruth runs the school office and has four new teaching assistants starting at half past eight. They need to be on the all-staff e-mail list before the head's welcome message goes out at nine. There is an article. Step 3 says: "Open the group, add the new members and save." She opens the group. She searches for each name and selects it. The Save button is grey and will not click. She selects the names again, more firmly. She closes the window and starts over. At 08:10 she phones the desk. Marcus, who has done this a hundred times, says "did you click Add to move them across to the right-hand pane first?" She had not, because the article had not said so, because to Marcus clicking Add is not a step. It is part of adding.

A step is one action the reader takes, written in the exact words they will see on the screen, followed by what they should see when it is done. One action, not two; the words on the screen, not a paraphrase; and a result to check before moving on. That rule is the whole of this article. It is harder to keep than it sounds. The person writing the step cannot see which of their actions are actions and which are, to them, just part of doing it. This article is part of our Writing KB Articles People Can Actually Follow series. It is about the step itself. Where the steps sit in the article and what surrounds them is in The Anatomy of a Followable Article.

It covers why one action per step is the rule, then writing the exact words on the screen. Next come the result line after each step and the trap step that everyone misses. We cover the words that tell the reader it should have been easy, then steps that are checks, waits and forks rather than actions. We finish with a short war story and the step-writing rules to copy, in that order.

Why One Action per Step

A reader following instructions does not read the article. They read one step, look at the screen, do the thing, look back at the article, and find their place again. That loop runs once per step, and anything that breaks it costs the reader their place. A step with two actions breaks it in the middle: the reader does the first action and looks up to check. When they look back they have either done both or neither, and cannot tell which. "Open the group, add the new members and save" is three loops written as one. Ruth did the first and the third and skipped the one that was hidden between them.

The second reason is that a step is also the unit of failure. When something goes wrong, the reader needs to be able to say "it went wrong at step 4", to themselves and to the desk. The desk needs to be able to ask "what did you see after step 4?" and get a useful answer. A step that contains three actions makes "step 4" meaningless as a location. That is why the first question on the call becomes "what exactly did you do?" That is the question the article existed to make unnecessary. One action per step is as much for the person who takes the ticket afterwards as for the reader.

The objection is that it makes articles long, and the objection is wrong in the way that matters. An article with fourteen steps of one line each is read faster and finished more often than one with six steps of three lines. The reader's loop runs fourteen clean times instead of six broken ones. Length on the page is not effort for the reader. Re-reading is effort for the reader. The step count is a number nobody is scoring. (Nobody has ever abandoned an article because the numbers went past ten.)

Write the Exact Words on the Screen

Every step names the thing the reader acts on by the words that are printed on it, with the same capital letters. It never names the thing by a description of what it does. "Click Approve selected" is a step; "approve the entries" is a hint. The reader is scanning a screen for a word that matches the article. If the article says "the save button" and the screen says "Apply", they will look for Save until they give up. Where the control has no label, describe it by its shape and position: "the gear icon at the top right", "the three dots beside the file name". Then stay consistent. If the article calls it the gear icon in step 3, it is the gear icon in step 9, not "settings".

Use one verb per kind of action and keep it the same throughout the knowledge base. Use click for a mouse or trackpad, tap for a touch screen, and press for a physical key. Use type for text, select for a choice in a list or a menu, and tick and untick for boxes. The reader does not notice when the verbs are consistent, and notices immediately when "select" means three different things in one article. For a path through menus, write each stop in order with the same separator every time: "Click Settings, then Accounts, then Add an account." Anything the reader must type goes in quotation marks, exactly as it must be typed, including any dots or dashes, with a note on whether capitals matter.

The exact words come from the screen, not from memory, and that means the writer has the system open while writing. I have never once written a menu path from memory and got every label right. The system I am surest of is the one that renamed a tab two upgrades ago without telling me. Do the task while writing the step, read the label off the screen, and write it down. The step is a transcript, not a recollection. The rule about plain words elsewhere in the article, no jargon the reader has not been taught, still applies. Skipping the Jargon covers it. Inside the step, though, the screen's word wins even when it is jargon, because the screen is what the reader is looking at.

The Result Line After Each Step

After every step, write what the reader should see when the action has worked, in one line beginning "You should see". "Click Approvals. You should see: a list of names, each with a tick box." The result line turns a step into a check. A reader who sees the list is on course and carries on. A reader who sees something else stops at this step, knows that this is the step that failed, and has a sentence to put in the ticket. Without the result line, the reader carries on through four more steps with the wrong screen in front of them. The failure surfaces somewhere that has nothing to do with its cause.

Some results take time, and the result line says so. "Click Connect. Within about a minute, you should see: the word Connected in green." A reader who is not told to wait will click again, and the second click is usually what breaks it. Some results are invisible, and the result line says that too: "Press Enter. Nothing visible happens; that is correct. Go to step 6." A reader who expects a change and sees none assumes failure and starts over. "Nothing happens" is a perfectly good result, as long as the article says it was expected. It is the unexplained nothing that sends people back to step one.

Write the result from what is on the screen, not from what the system has done. "The account is now created" is a statement about the system, and the reader cannot see the system. They can see a message that says "Account created" at the top of the page, so write that. Where the result differs between readers, say what varies: "You should see: your name at the top right and between three and six tabs, depending on your role." The result line is the reader's only instrument. Give them a reading they can take, not a conclusion they would have to trust.

The Trap Step Everyone Misses

Every procedure of more than four steps has one step that the writer does without noticing and the reader cannot do without being told. And that step is where most of the tickets come from. Ruth's trap was the Add button that moves names from the left pane to the right. Others are everywhere: the Save button that stays grey until a box further down is ticked, or the confirmation dialog that opens behind the main window. There is the setting that is saved but does nothing until the reader signs out and back in. There is the second "Are you sure?" that appears only on the first use. There is the page that must be scrolled to find the button, or the field that must be clicked away from before the value takes. To the writer, each is part of the action it belongs to. To the reader, each is an invisible wall.

Trap steps are found, not remembered, and there are two places to look. The first is the tickets: read the last ten tickets about the task and list what the user said they did and what they saw. The trap is the step at which the users' accounts stop matching the article. If you run QuerySolv, every ticket keeps its complete event history. That means the user's own words about what they clicked are still there to read months later. That is exactly the evidence this search needs. The second is a stranger: hand the draft to someone who has never done the task, and watch without speaking. And the trap is the step where they stall. That test, with the rule about how many people to try it on, is in Testing Articles on Real Users. Between the tickets and the test, the trap steps turn up within a week. I have never found one by rereading my own draft, and I have tried.

Once found, the trap step gets three things that an ordinary step does not. It gets its own number, because it was a hidden action and the cure for a hidden action is a visible one. It gets a line saying what the reader sees if they have missed it. That is how the reader will discover they have: "If Save is grey, you have not yet clicked Add; go back to step 4." And it gets its rescue in the "if it did not work" section at the end of the article, in the same words. Readers who have fallen into the trap go to the end of the article looking for help, not back to step 4. The table below lists the common traps, what the reader sees when caught, and the step that frees them.

The Words That Say It Should Have Been Easy

Cut "simply" and "just" from every step, and cut them from the rest of the article while you are there. "Simply click Add" and "just tick the box" contain no information that "Click Add" and "Tick the box" lack. They carry one message the writer did not intend: this is easy, and if you are stuck, that is on you. The reader who is stuck at that step is the only reader who is reading it closely. The article is telling them that they should not be stuck. Every word that comments on the difficulty of a step is a word addressed to a reader who is not having difficulty, and that reader is not reading.

The same cut applies to "easily", "quickly", "straightforward", and "intuitive". It also applies to the pair that did the damage at Larkfield: "as usual" and "in the usual way". There is no usual way for a reader doing something for the first time. "As required", "as appropriate", "relevant" and "the correct option" belong in the same bin, because each one is the writer declining to say which. "Select the appropriate option" means "I know which option, and I am not going to tell you." Say which. If it depends, say what it depends on, in a fork, which is the next section. Then there is "etc.", which means "there are more, and you will have to guess them", and is never acceptable in a step.

The test for any adverb or qualifier in a step is to delete it and read the step again. If the step lost nothing, the word was decoration. If the step lost something, the something was a fact the writer was hinting at instead of stating, and the fix is to state it. "Quickly click Yes before the box disappears" loses something when "quickly" goes, and what it loses is a fact: the box disappears after a few seconds. Write the fact. "Click Yes. The box closes by itself after about five seconds; if it has gone, press the Refresh key and it comes back." The adverb was a symptom. (Most adverbs in instructions are symptoms, and the condition is called knowing too much.)

Checks, Waits and Forks

Not every numbered line is an action, and three other kinds of step have their own shape. A check is a step whose action is to look: "Check that the week shown at the top is the week just ended." Write it as a step, and give it a result line like any other ("You should see: last Monday's date"). Follow it immediately with what to do if the check fails. A check with no failure path is a check the reader cannot act on. A wait is a step whose action is to do nothing for a stated time: "Wait until the progress bar fills, which takes up to two minutes. Do not click anything during this time." Say how long, say what the reader sees when it ends, and say not to click, because they will.

A fork is a step at which different readers do different things. And it is the step most likely to go wrong, because the reader has to recognise which branch is theirs. Fork once, early, and send each branch to its own run of steps: "If you are on a laptop, go to step 6. If you are on a desktop, go to step 10." Never fork inside a step ("on a laptop click X, otherwise click Y") and never fork more than once in an article. A reader following two forks is in one of four paths and the article is no longer one procedure. If the branches are long, they are two articles, each with a clear audience line, and the fork is a link at the top of each.

The last special case is the step that is really another procedure. "Convert the receipt to a PDF" is one step in the expenses article and eight steps in its own right. The choice is between inlining eight steps into an article about something else or linking to an article that owns them. Link, nearly always. Write the step so that the reader knows they are leaving and coming back: "Convert the receipt to a PDF, following 'How do I turn a phone photo into a PDF?', then return here for step 5." The same reasoning decides when a step needs a picture rather than more words, which is the subject of When a Picture Beats the Steps. A step that describes where something is on an unfamiliar screen is often shorter as a cropped screenshot than as a sentence.

Write the draft where only the desk can see it until the trap steps have been found, then make it public. Most knowledge bases allow an article to be visible to the support team only or to everyone. So a draft can live in the real knowledge base from its first day without a user following it before it is ready. Technicians should follow the draft on real tickets for a week and note the step at which the user on the phone stalled. That is how the trap steps come to light. The same discipline of writing steps a stranger can repeat applies inside the ticket itself, where the note that records what was done has to survive a handover. Writing Reproducible Steps covers that side, and the two habits reinforce each other.

A Short War Story: The Claims Export at Stonebridge Insurance

Stonebridge Insurance had an article for running the monthly claims export from the claims system. Step 4 read "Choose the date range and untick Include archived, then click Run." Most people who followed it chose the range and clicked Run. The untick was in the middle of the sentence and the box was below the part of the page they could see. The export therefore included nine years of archived claims, took twenty minutes instead of two, and produced totals that were wrong by a large and inconsistent amount. Farah on the desk counted thirty-one tickets in one month that came down to that step, at a little over ten minutes each. That is five hours of a technician's month spent saying "scroll down and untick the box". In the same month a regional manager sent the inflated figures to the board, who asked why claims had tripled. The rewrite split step 4 into three steps with a result line each. The untick got its own number and a line saying "if the box is not visible, scroll down". The tickets stopped the following month. The step had been in the article the whole time. It had been there as a clause, and a clause is not a step.

The Step-Writing Rules

The rules below are the article as a checklist, meant to be kept open beside the draft and run over every step before the article goes to the editor. Most steps will fail one rule on the first pass, usually the result line or the exact wording. And the fix is a minute each. The last three rules are the ones that find the trap step. And they are the ones that cannot be done by the writer alone.

STEP-WRITING RULES — ONE PAGE
Article: ________________________________   Steps: ____   Checked by: ________

FOR EVERY STEP
  [ ] One action. If the step has "and" or "then" in it, it is two steps.
  [ ] Starts with the verb: click, tap, press, type, select, tick, untick.
  [ ] Names the control by the words printed on it, with the same capitals.
  [ ] Unlabelled controls described by shape and position, the same way
      every time ("the gear icon at the top right").
  [ ] Anything to be typed is in quotation marks, exactly as typed.
  [ ] Menu paths written as stops in order: "Click A, then B, then C."
  [ ] A result line: "You should see: ______." Written from the screen.
  [ ] Waits say how long and say "do not click".
  [ ] Invisible results say "nothing visible happens; that is correct".

FOR THE WHOLE PROCEDURE
  [ ] No "simply", "just", "easily", "quickly", "straightforward".
  [ ] No "as usual", "the usual way", "as appropriate", "as required",
      "relevant", "the correct option", "etc."
  [ ] Checks have a failure path in the next line.
  [ ] At most one fork, early, sending each branch to its own steps.
  [ ] Sub-procedures are links, with "then return here for step __".
  [ ] Every label was read off the live screen today, not remembered.

FINDING THE TRAP STEP
  [ ] Last ten tickets about this task read; step where they diverge: ____
  [ ] One stranger followed the draft while I watched; step they stalled at: ____
  [ ] The trap step now has its own number, a "you should see", and a line
      saying what the reader sees if they missed it.
  [ ] The same rescue is repeated under "If it did not work".

Ruth's article was rewritten that afternoon by Marcus, who did the task on a test account while writing. He found, to his surprise, that it was seven steps and not three. Step 5 became "Click Add. You should see: the selected names move to the right-hand pane headed Members, and the Save button turn from grey to blue." Nobody has phoned about the all-staff list since, which Marcus initially put down to a quiet term. It was not a quiet term. The article had simply stopped hiding a step.

Frequently Asked Questions