If you give an instruction in your documentation without setting expectations, you might be setting up your reader for confusion or task failure. Here’s a pattern for writing step-by-step directions with more clarity.
Documentation that helps people carry out specific tasks often contains step-by-step directions, like this:
This is a poor, though common, practice. I’ve committed this offense against readers myself, because it’s easy to do. Or to put it another way, it’s easy to not do the important bit. Here’s what I should’ve written:
The difference in the second example is that the steps not only tell the user what they should do, but it also gives them clues about what to expect from each action.
If you’ve ever done usability testing–or even some tech support for friends and family–you’ve seen what happens when people don’t know what to expect. Someone successfully works through a series of steps, only to stop, unsure whether they’ve done the right thing even when they’ve worked through the steps flawlessly.
This happens when the person working through the steps doesn’t have a way to gauge their own success or failure. This problem is less pronounced when working through directions for physical objects. Many real-world interactions have dramatic feedback. For example, if you wanted to tell someone how to start a car, turning the key in the ignition or pressing the start button typically has clear feedback, with simultaneous sounds, vibrations, and visual indicators to punctuate success and failure.
While most user interfaces provide a minimum level of feedback on interactions (e.g., a button cycles through an animation when clicked), software, with its abstraction from the physical world, frequently cannot provide a more visceral sense of success or failure. With the added complexity of numerous mouse clicks and button presses to complete even simple tasks, it’s no surprise that users get confused even when they’re doing everything right.
And that’s why it’s important to set expectations in your directions. It’s not enough to simply tell your audience what to do, you also have to show them what success looks like.