RE: Style Question

["Ridder, Fred" <Fred.Ridder@xxxxxxxxxxxx>]

I know that "I agree" postings are normally considered bad form on e-mail
mailing lists, but Mike is so squarely on the mark with his comments that 
I just had to say it.  Consistency is the key; the more consistent you can 
be in verb usage the more effectively you can implement notational
shortcuts because the context will be less ambiguous to the reader.

My opinions only; I don't speak for Dialogic or Intel...
Fred Ridder (Fred.Ridder@Dialogic.com)
Senior Technical Writer
Dialogic, an Intel Company
Parsippany, NJ



-----Original Message-----
From: Mike Tatro [mailto:tatro@vsi.com]
Sent: Wednesday, September 06, 2000 4:28 PM
To: 'Ada Lai'; 'framers@omsys.com'
Subject: RE: Style Question


Ada-

Where what I do...

I consistently use the verb "choose" when documenting commands. I also use
the FM documentation convention of connecting sequential commands with a
greater-than (>) sign. For example:

Choose File > Open.

I also bold all commands in my manuals and this in the Foreword so that new
readers understand my conventions for sequential commands.

Personally, I definitely find that consistently using the same verb to mean
one specific thing is very helpful. For example, I always use "choose" for
commands, "click" in connection with GUI buttons, I always use "select" when
instructing someone to pick something from a list and I use "press" when
referring to QWERTY keys. Most importantly, I NEVER mix them. I find that
consistent use of verbs sends important clues to the user. It establishes a
rhythm to the material - my readers always know that "choose" precedes a
command and nothing else. 

Consistent verbs also help make the material more concise. For example, I
think "Click OK" is more concise than "Click the OK button." Again, if I
always use "click" in connection with a GUI button, the reader is not
confused.

This is all food for thought. Certainly plenty of writers do this
differently than I do. I think purposefulness and consistency are the
important criteria here. Most hack writers seems to use any old verb they
feel like whenever the mood strikes them (indeed, the concept of reserving
verbs for particular actions is something they aren't even aware of). We
professionals ought to hold ourselves to a higher standard.

I hope this helps.

Warmest Regards,
Michael L. Tatro
Documentation Manager
V-Systems, Inc.
tatro@vsi.com 



** To unsubscribe, send a message to majordomo@omsys.com **
** with "unsubscribe framers" (no quotes) in the body.   **