Re: Step structure (was RE: a question about verb tense/is or was?)

["Hager, Harry (US - East Brunswick)" <hhager -at- dc -dot- com>]

Hi,

I get the digest so, I'm a little late to this thread that has mutated into
a discussion of how to word steps in a procedure.

I'm adding some comments because nobody has written about the method I use,
which goes something like the following example. (There is nothing unique
about this method. I've stolen it from several other sources, too numerous
to name.) 

> To do this:

	1. Do this first. (From the ABC menu, select DEF)
	   This is what happens. (The XYZ program displays the DEF window.) 

	2. Do this next. 
	   This is what happens.

	3. Do this next.
	   This is what happens.

Here's what I'm doing here:
- Every procedure performed by the user is a numbered list. No procedure the
user performs is ever buried in a sentence in a paragraph. 
- Every procedure performed by the user has a stem that tells the user what
is to be accomplished. (To do this:)
- The stem is always bolded and always has a graphic element at the front. I
typically insert an arrow or arrowhead from the Wingding font or some other
font I have access to. In the Conventions section in the front of the book,
I explain that these typographic elements, bold & arrowhead, indicate a
procedure to be performed by the user.
- Every step in the procedure almost always has two parts; first is the
action the user takes, second is the resulting action performed by the
program. I include the second part here to reinforces to the user that they
are doing the procedure correctly. If I tell the user that the ABC window
displays but the XYZ window displays instead, the user knows that something
is wrong and can quickly backtrack. The second part is not needed in some
very simple steps, such as telling a user to locate something on the screen
or telling the user to position the cursor on an element in the window.
- I am consistent with this structure throughout the book, regardless of how
simple or complex the procedure. The next book may have some changes to this
structure but all the user procedures in that book will also be consistent.
- I write for the user who is reading the procedure for the first time. No
short cuts. No multiple step windows procedures merged into one. I figure
that experienced users of our software will make notes for the shortcuts
they may develop.

I make the following assumption about the user:
- The user is familiar with Windows, meaning that they know how to use a
mouse, they know what a menu is, and so on. I state this explicitly
somewhere in the first chapter and point them somewhere else if they don't
know this information. Sometimes in the first or second chapter, I might
have a short refresher on some windows elements or structures that are key
to using the proprietary software I'm writing about. 

This structure is for user manuals, not quick reference guides, crib sheets,
or whatever we might call those little job aids. 

I invite any and all comments about this structure I write for user
procedures. 

H. Jim Hager
hhager -at- dc -dot- com




This message (including any attachments) contains confidential information
intended for a specific individual and purpose, and is protected by law.  If
you are not the intended recipient, you should delete this message and are
hereby notified that any disclosure, copying, or distribution of this
message, or the taking of any action based on it, is strictly prohibited.


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

*** 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

A landmark hotel, one of America's most beautiful cities, and 
three and a half days of immersion in the state of the art:
IPCC 01, Oct. 24-27 in Santa Fe.  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.