Use of voice and commas in procedures

Subject: Use of voice and commas in procedures
From: "Geoff Hart (by way of \"Eric J. Ray\" <ejray -at- raycomm -dot- com>)" <ght -at- MTL -dot- FERIC -dot- CA>
Date: Thu, 5 Nov 1998 11:57:39 -0700

Jim Lockard had a few questions about the use of grammar in
procedural material. Since Eric doesn't like grammar discussions on
techwr-l, I'll put a technical writing spin on the answers (which
should raise a few interesting threads) and de-emphasize the grammar:

<<Type a new filename, and click OK>>

It's unnecessary to include the comma before the "and", and
unnecessary punctuation only slows comprehension. Moreover, it's
probably better to use "then" instead of "and", because "and" has the
connotation of simultaneity and that could prove confusing to some.

<<We often use the imperative voice (or is it a "tense") when we
write instructions.>>

It's a voice, and it's the preferred method of writing instructions
because it makes the actor clear; passive voice is only acceptable
in instructional material if the actor is irrelevant to the
instruction, and that's rare indeed. However, in your example:

<<Choose Save from the File menu.>>

It's generally better to provide the context first, then the action
that occurs in that context. Thus: "From the File menu, choose Save".

<<The grammar rules I know clearly call for a comma before a
conjunction that joins two independent clauses. Take, for example,
the sentence, "A Windoze PC is a hobby, but a Macintosh is a tool.">>

That's not a grammatical rule, but rather a matter of style. In
many cases, though, it's the right style. For example, here, the
comma cues readers to pause and absorb the first thought (to take a
mental "deep breath") before proceeding to the second clause. The
presence of the comma is occasionally a hint that you may need to
break a long, compound sentence into two steps.

<<Since the subject is implied, can we not assume that the second
clause ("click OK") is not truly independent in that it shares the
subject with the first clause--as in, "I read the directions and
crashed my computer"?>>

That's a more interesting question, but not because of the
punctuation. The general rule of thumb is that each numbered step
should contain a single action. As you note, the OK is not
independent because it completes the action just like a period
completes a sentence. Thus, it belongs in the same step.
--Geoff Hart @8^{)}
geoff-h -at- mtl -dot- feric -dot- ca

"By God, for a moment there it all made sense!"--Gahan Wilson

From ??? -at- ??? Sun Jan 00 00:00:00 0000=

Previous by Author: ROI of online help?
Next by Author: Commas, take II
Previous by Thread: Re: Comma rules and the imperative
Next by Thread: Referring to HTML tags in documentation

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

Sponsored Ads