Re: grammar survey

[Kurt Hebner <khebner -at- DECISIONISM -dot- COM>]

Chris--

It is always a good idea to put the conditions under which you perform an
action before the action itself. It is certainly less important in a
software (well, depends on what it does, I guess) manual than in a
procedure for a nuclear power plant, but it's still a good idea. It's also
(perhaps) more important for 'if' statements than 'when' statements, but
still important.
You can think of most computer languages -- they have 'if...then'
statements (or 'while...then' or whatever), not 'then...if' statements.
When this subject comes up, I am always reminded of the M*A*S*H episode
where Frank (I think -- anyway, whoever it is is safe behind the sandbags)
is reading the bomb defusing manual to Hawkeye, who has wire clippers at
the ready. Frank, reading from the manual, says, "Cut the red wire."
Hawkeye cuts it. Frank says, "After you have cut the blue wire." And of
course they all go running.

The bottom line is that when you tell the user to do something, any
qualification has to be up front, or else she may go ahead and do it
without reading what comes next. Depending on your industry, this could be
a small or large problem.

As for finished or done, perhaps done is better because it's only one
syllable. Unless this procedure is intended to be read aloud by one person
and performed by another, in which case, you would want to think of
homonyms and potential mix-ups. I have heard that in military manuals they
do not use the word 'close' when referring to what you do with a valve,
because the long 'o' (when yelled from one person to another in a noisy
environment) could be construed as the sound in 'open'. They use the word
'shut'. FWIW

--Kurt

Kurt Hebner
Decisionism Inc.
Boulder, CO
khebner -at- decisionism -dot- com




-----Original Message-----
From:   Hutchings, Christa [SMTP:cwhutchings -at- HOMEWIRELESS -dot- COM]
Sent:   Sunday, May 17, 1998 12:16 PM
To:     TECHWR-L -at- LISTSERV -dot- OKSTATE -dot- EDU
Subject:        grammar survey

Hi gang -

Vote for your favorite:

1) When finished, press END.
2) When done, press END.
3) Press END when finished.
4) Press END when done.

There's a raging debate here on my technical review team as to which is
the correct construction. Some don't like "when done" as it makes them
think we're baking a cake, others don't like "when finished" and are
adamant that "when done" is perfectly acceptable. Some want the action
to be taken at the front of the sentence, others want the time to take
the action at the front of the sentence.

I've heard and read plenty of good arguments for each construction and
am wondering how you folks feel about them.

Chris Welch-Hutchings
Sr. Technical Writer
Home Wireless Networks, Inc.
Norcross GA (USA)
cwhutchings -at- homewireless -dot- com