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

["Giordano, Connie" <Connie -dot- Giordano -at- FMR -dot- COM>]

Kevin,

A perfectly admirable and efficient approach for strict task-based, or
context-sensitive help.  Scares the bejesus out of my incredibly bright
financial planner/investment professional-type audience who has spent the
last ten years working on mainframe green screens with cryptic names.  I
know enough about the audience for what I'm working on now to know they need
something, short and to-the-point, but something to help indicate that
they're working on what they think they're working on.  By the time they
understand that this thing that was called "such and such" in the mainframe
is now called "this and that" on the desktop, they're not going to be using
the manual anyway.

Do I hear two bits?

Connie Giordano

-----Original Message-----
From: KMcLauchlan -at- chrysalis-its -dot- com
[mailto:KMcLauchlan -at- chrysalis-its -dot- com]
Sent: Thursday, March 22, 2001 1:52 PM
To: TECHWR-L
Subject: RE: Step structure (was RE: a question about verb tense/is or
was ?)


I'll see your 10 and raise you another nickel.

If I see "To erase your hard drive, click Mumble..." 
I'll take that as "If this is what you'd like to 
do, this is how to do it... but if you don't wanna..."

Normally, in my instructions, I want the reader 
to do the action. The only reason they are SEEING 
the instruction is that they have reached the step 
where it is necessary.  If the action is something 
particularly dangerous and irrevocable, I might 
say it as "Erase your hard drive by clicking Mumble."

Even that, I find to be almost annoyingly pandering 
to stupidity.

My approach is: If you need to know something, I'll 
either explain it before my doc requires you to make 
a decision on it, or I'll have told you in the pre-amble 
what experience or knowlege you are expected to bring 
to the table.

I use present tense almost exclusively. In my docs, 
the reader is always in the thick of the action.  :-)

1. Do this.
2. This happens. Now do that.
3. The other happens. Do this...

Some people have made the point that they use 
future tense if the sequence pauses until something 
else occurs (duration of pause specified or unspecified).

My policy is that I tell the reader what to do NOW, 
and I warn her that there may be a delay, but I 
don't linger on the before side of the temporal gap.
I go to the next point at which the reader must engage 
the process and I give them a new NOW.  In my instructions, 
NOW keeps moving with the flow of events. You can't do 
much about the past. The future ain't here, yet. 
As for the present... well, it just happens that I have 
this little task for you... Oh, and look! Here's ANOTHER 
little observation or task to fit this BRAND NEW NOW!.... 
and like that... :-)

Also, as illustrated in my sample steps, above, I reserve 
numbered steps for what the reader does. That is, after telling 
the reader a couple of consecutive things to do, I won't 
give a separate numbered step for something the equipment 
(or program) does.  Instead, I try to make the reader's 
action occur either as the only thing in a particular 
step, or as the LAST thing written in the step.

If the reader's action in step 1 triggers some event 
or display that they need to know about, then I begin 
step two by telling them 
"2. The QWERTY dialog box appears, with three options.
    Choose the one that matches your eye color."

I try to keep the actual imperative on a line by itself, 
and I try to keep it... imperative, not mixed or qualified.

On the occasions when I list a set of "vague" steps or 
a sequence of events that is intended to presage or inform, 
but which I don't actually want the reader to do right now, 
THEN I might use the word "will"... one time.
"In this section, you will accomplish the following:

  - bullet item (see section title "Blah, blah")
  - bullet item (see section title "Yadda, yadda")
  - yet another bullet item (see section title "Oop, eep")."

But, when they go to any of those sections, they find themselves 
immersed in the eternal, step-by-step NOW.

YMMV

/kevin

> -----Original Message-----
> From: Marguerite Krupp [mailto:mkrupp -at- cisco -dot- com]
> I'll raise that to 10 cents!
> 
> Putting the condition before the action is a smart idea. 
> People tend to DO
> the action first, then read the rest of the sentence. Thus, I'd write:
> 
> To erase your hard drive, click Mumble...
> 
> 
> instead of:
> 
> Click Mumble to erase your hard drive.
> 
> Imagine the screams of anguish in the first case from users 
> who clicked
> first and read the condition afterwards!


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

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