An Article That Changed My Approach to Help

by Tom Johnson on Aug 7, 2008
categories: technical-writing

After a topic title in your help, what do you write? Do you jump straight into the numbered steps, or do you explain why a user would likely perform the topic?

Although I practice the latter (adding explanatory text before the steps), I recently read an article by Mike Hughes that convinced me readers rarely read text that appears before a numbered list.

Here's the gist of Mike's article. He's really talking about on-screen text, but I'm extrapolating the principle to apply it to my online help.

When using an application, users are motivated to take action, and their focus is easily drawn to action objects such as menus, buttons, and text fields.

Once an action object or other visual element on a page has drawn a user's focus downstream in the focus flow, it is difficult to redirect it back upstream. In other words, if something initially draws a user's attention to the middle of a page, it is far more likely that the user will continue across and down as opposed to going back up the page. This is especially true if there are additional action objects downstream.

See "Instructional Text in the User Interface: Some Counterintuitive Implications of User Behaviors" for the full article.

Two weeks after reading the article, it still rattles around in my mind. I think just like a button on a page, users are drawn to a numbered list. Although I still add some "why" or "when" before my numbered lists, if the information is critical, I insert it somewhere in the list.

Here's an example.

The information about why you'd want to make a spinach shake precedes the numbered steps. But the critical information about using frozen peaches is embedded in the list because readers would most likely skip over it in the introduction.

Thanks for a great article Mike. By the way, Mike's blog is here.

And if you want to read more about Shrek shakes, see Jane's post: "Shrek Shakes and Twinkies." We went through a 3 week period at our house where we drank nothing but Shrek shakes. Then one day my oldest daughter said she was sick of them, and we all agreed and haven't drunk them since.

----------

Note: I posted Mike's article on Writer River, as well as a ton of other excellent articles. Have you discovered Writer River yet? You can subscribe to the feed or to a daily email update. Then each morning, when you open your feedreader or email, you can start the day off with information that will help you do your job better.