Imperatives in procedures?

Subject: Imperatives in procedures?
From: Geoff Hart <ghart -at- videotron -dot- ca>
To: TECHWR-L <techwr-l -at- lists -dot- techwr-l -dot- com>, Jeff Scattini <jeff -dot- scattini -at- gmail -dot- com>
Date: Mon, 21 Nov 2005 17:33:26 -0500

Jeff Scattini wondered: <<I'm currently writing a series of task-oriented documents for a software application. I learned that one should always put the user-imperative at the beginning of each step: 1. Click Start on the toolbar... However, one of my product managers wants to bury the imperative in surrounding text: 1. On the left-hand side of the toolbar, click the Start button.>>

Which is better depends on your audience. The advantage of putting the navigation information up front is that new users need this information because they haven't yet learned where to look. The problem is that phrases such as "left side of toolbar" require the reader to construct a mental image of what the toolbar looks like, then seek that mental image somewhere on the screen. That's less of a problem for menus, of course, since the word used in the procedure can match the word used in the interface.

Conversely, putting the navigation information ahead of the actual instructions justifiably annoys skilled users of the software, since they already (largely) know where to look. Why make them read twice as much text if it's not necessary? Best to simply eliminate this information entirely for their sake... but then, what about the poor newbies who need it?

The solution for both users is simple: combine text with graphics. In the text part of the instruction, state only the imperative. "Click Start." Then accompany this with a graphic at the right that shows an actual picture of the thing that must be clicked or the location in which information should be typed or selected. This provides the missing support for those who need it, and doesn't force them to guess what visual image they should be seeking (particularly important for obscure icons with no obvious textual description). Those who don't need it can simply ignore the graphic.

Of course, this can get messy if you have many procedures that require reference to the screen images. In that case, an elegant and effective solution is to provide a single screenshot, with the instructions arranged neatly around it in a logical order (e.g., clockwise from top left). That way, the instructions are tied directly to the images readers need to look at to know where to do things--and the pros can still ignore the image and focus on the words.

But what about simple things like clicking on the Start button? For some of this, you can get away with the standard "We assume you already know how to use Windows" assumption. After all, it's kind of messy and expensive having to add 500 pages of Windows documentation to your 500-page product manual. How can you know what to omit? Ask the users. They're the ones who can tell you.

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --
Geoff Hart ghart -at- videotron -dot- ca
(try geoffhart -at- mac -dot- com if you don't get a reply)
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -


Now Shipping -- WebWorks ePublisher Pro for Word! Easily create online
Help. And online anything else. Redesigned interface with a new
project-based workflow. Try it today!

Doc-To-Help 2005 now has RoboHelp Converter and HTML Source: Author content and configure Help in MS Word or any HTML editor. No proprietary editor! *August release.

You are currently subscribed to TECHWR-L as archive -at- infoinfocus -dot- com -dot-
To unsubscribe send a blank email to techwr-l-unsubscribe -at- lists -dot- techwr-l -dot- com
or visit

Send administrative questions to lisa -at- techwr-l -dot- com -dot- Visit for more resources and info.

Imperatives in procedures?: From: Jeff Scattini

Previous by Author: Xtreme Programming / Agile Development and Documentation
Next by Author: Career path in the third and fourth decades?
Previous by Thread: Imperatives in procedures?
Next by Thread: Re: Imperatives in procedures?

What this post helpful? Share it with friends and colleagues:

Sponsored Ads

Sponsored Ads