Step structure? Where to put the context depends on your audience

["Hart, Geoff" <Geoff-H -at- MTL -dot- FERIC -dot- CA>]

Christian Walters, discussing whether the action or the context should come
first in procedural steps, believes: <<...it all depends on a lot of
factors... If you're dealing with a step that can bring about the end of the
world, by all means get that point across at all costs.  But not every click
is deadly.  I read some study (Jared Spool's, I think?) that encouraged us
to
put the most important part of the step in the first three words, and I've
found that to help with readability and speed.>>

As you note, it depends. There's no question that important context (such as
warnings that might lead the reader to reconsider an action) must come
first, but that doesn't mean the action should always precede the context in
other cases. Granted, if you're dealing with an audience of experienced
users of the software, there's no need to say "Open the File menu and select
Save", since "save your file" is shorter and more direct; they already know
how to save files, so all you need to tell them that the time has come to
save, not how to do it. The problem comes when you get into less familiar
procedures and can't guarantee that your audience already knows what to do
or why. For those who already understand the software and are using the
steps only as a reminder of what they must do, the context is either
unnecessary (as in this example) or can follow the action (as a reminder in
case they've forgotten). However, that ignores the needs of those who are
consulting the documentation because they don't know how to do the
procedure.

An interesting compromise might be to adopt a minimalist approach: at the
start of the step, provide the action all by itself ("Save the file"); on
the following line, indented to mark it as secondary information, you
provide the details (e.g., "in the File menu"). This would be particularly
effective in a future online help system that lets the user interactively
change the level of detail; for example, expert users would simply toggle a
switch so that the secondary line no longer appears on-screen; when they
encounter something where they need that additional detail, they toggle the
display to reveal that second line.

<<When I first opened my mouth, I was thinking of something like this: Click
Copy from the Edit menu. versus From the Edit menu, click Copy. In this
example, I think "click Copy" is the most important part and should go right
at the front of the sentence, and that's the standard I've managed to sell
here in my group.>>

It's not that this approach is wrong, but rather that it seems less
efficient for the part of your audience that doesn't already know the
location of the Copy command. (That's a trivial example, but consider
something more complex such as setting preferences: are they under the Edit,
Tools, File, or Special menu? I've seen them in all these places.) Consider
the thought process for an experienced user, who just wants to know what to
do (rather than learning why) as they read the first clause in your
preferred version:

Click Copy [user moves mouse directly to the Edit menu, already knowing
where the command lies, then reads the second part of the sentence and
discovers it's unnecessary detail]

Compare this with the thought process of the inexperienced user:

Click Copy ["Where's that? Keep reading to find out!"] in the Edit menu
["aha! that's where they hid it"... begins moving mouse to that menu]

Not a huge difference, but slower than simply opening the Edit menu and
scrolling down to Copy. Repeat that slightly slower process for every step
in your manual, and the small problem becomes a bigger one. Are these
differences truly meaningful? The difference of opinion on this matter
suggests that nobody's actually got hard data to confirm whether it's
significant. I believe it is, but can't prove it.

<<I've taken to using some variant of an If/Then table, especially if there
are multiple choices possible.>>

That's a very effective approach, and it reminds me of something I saw a
long time ago and can't now remember where: The commands were presented as a
three-column table, with the column headings "Step #", "Menu choice" (or
action), and "Menu" (or location). Readers scan the column headings
initially, and learn that the actions are in the middle and the explanations
are on the right; with this schema in hand (so to speak), they simply read
down the middle column, performing the steps one by one until they reach one
that isn't clear, at which point they read into the next column to find out
what to do. The first column serves only as a reminder of the order, and the
last column gets read only if they don't know what to do. Very minimalist,
and very effective for some people.

--Geoff Hart, FERIC
580 boul. St-Jean, Pointe-Claire, Quebec H9R 3J9
geoff-h -at- mtl -dot- feric -dot- ca 

^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

*** Deva(tm) Tools for Dreamweaver and Deva(tm) Search ***
Build Contents, Indexes, and Search for Web Sites and Help Systems 
Available 4/30/01 at http://www.devahelp.com or info -at- devahelp -dot- com

IPCC 01, the IEEE International Professional Communication Conference,
October 24-27, 2001 at historic La Fonda in Santa Fe, New Mexico, USA.
CALL FOR PAPERS OPEN UNTIL MARCH 15.  http://ieeepcs.org/2001/

---
You are currently subscribed to techwr-l as: archive -at- raycomm -dot- com
To unsubscribe send a blank email to leave-techwr-l-obscured -at- lists -dot- raycomm -dot- com
Send administrative questions to ejray -at- raycomm -dot- com -dot-  Visit 
http://www.raycomm.com/techwhirl/ for more resources and info.