RE[2]: Single-step procedures

Subject: RE[2]: Single-step procedures
From: "Ridder, Fred" <F -dot- Ridder -at- DIALOGIC -dot- COM>
Date: Tue, 5 Aug 1997 17:37:14 -0400

I've had much the same reaction as Geoff Hart--at first
believing that numbering a single-step procedure is
foolish, but eventually coming around to the belief that
structural consistency is probably important enough
to warrant the foolish-looking number.

I do still think that a single, numbered step all by itself is
likely to cause some readers to waste time and energy
looking for Step 2. (These may be the same readers
who will look around for the "missing" page if you leave
out the silly "this page intentionally left blank" legend,
but they are still part of the audience, nonetheless.)
Various posts on this thread have suggested at least
three good approaches to solving this problem:

1) State in the text preceding the single-step procedure
that the procedure has but a single step, as suggested
by Robert Plamondon, but I feel it is probably the least
successful approach because it relies on information
that is located upstream from the problem area. A
reader who is in a panic is more likely to search
downstream for the "missing" step 2 than to read the
preceding paragraph.

2) Use some unambiguous flag to indicate the end of
_every_ procedure, as was also suggested by Robert
Plamondon. I'm really surprised that this issue was
under discussion for several days before this idea
came up, because it seems so obvious.

3) Make up some unnecessary step to make single-
step procedures into two-step procedures as suggested
by Geoff (and someone else, I believe).

Another approach might be considered a combination
of approaches 2 and 3. It seems to me that every
procedure has an implicit final step, which is to observe
that the desired operation has been accomplished. If
you write procedures that direct the reader to make
this observation, you kill two birds with one stone by
ensuring that every procedure has at least two steps
(do it, then make sure it's been done), and also signaling
to the reader that there are no more steps to the
procedure. And if the observation is described in
specific terms, this approach can also reassure readers
that they have correctly completed the procedure and
can safely proceed to the next procedure. This can be
particularly valuable when there is no way to undo a
procedure once you begin a new operation.

Fred Ridder (mailto:f -dot- ridder -at- dialogic -dot- com)
Senior Technical Writer
Dialogic Corporation, Parsippany, NJ

And to keep our marketing people happy:
Get the Dialogic Edge at: http://www.dialogic.com



-----Original Message-----
From: geoff-h -at- MTL -dot- FERIC -dot- CA [SMTP:geoff-h -at- MTL -dot- FERIC -dot- CA]
Sent: Monday, August 04, 1997 4:47 PM
Subject: Single-step procedures

My first reaction to the notion of numbering a single-step
procedure was that this represents a textbook example of
foolish consistency. But upon reflection, it starts to make
an increasing amount of sense. There's one particular case
where it would be absolutely essential; if you're working
in SGML, you wouldn't want to incorrectly tag the
procedural step as (say) "body text" just to get around the
number if the correct tag would be "procedure". You could
write your way around this, but making exceptions can come
back and bite you hard when you least expect it.

If you're not using SGML, it might be worth creating an
unnecessary second step so that the numbers wouldn't look
so odd. Even something as simple as "open file" could
become "1. pull down the File menu; 2. select the Open
command". It's not elegant, and I don't like it much, but
it might be a reasonable compromise in some situations.

--Geoff Hart @8^{)} geoff-h -at- mtl -dot- feric -dot- ca
Disclaimer: Speaking for myself, not FERIC.

TECHWR-L (Technical Communication) List Information: To send a message
to 2500+ readers, e-mail to TECHWR-L -at- LISTSERV -dot- OKSTATE -dot- EDU -dot- Send commands
to LISTSERV -at- LISTSERV -dot- OKSTATE -dot- EDU (e.g. HELP or SIGNOFF TECHWR-L).
Search the archives at http://www.documentation.com/ or search and
browse the archives at http://listserv.okstate.edu/archives/techwr-l.html


Previous by Author: Re: Symbols on Web Pages
Next by Author: Re: Choosing a menu option
Previous by Thread: Single-step procedures
Next by Thread: Re: RE[2]: Single-step procedures


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


Sponsored Ads