RE: Style Question

[Mike Tatro <tatro@xxxxxxx>]

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 

> -----Original Message-----
> From: Ada Lai [mailto:adalai2000@yahoo.com]
> Sent: Wednesday, September 06, 2000 12:45 PM
> To: 'framers@omsys.com'
> Subject: Style Question
> 
> 
> First, let me offer a belated thanks to all for your opinions 
> and rationale 
> offered last week on page numbering in large documents. 
> Everyone's comments 
> have helped me understand more about how page numbering can 
> relate to the 
> manner in which a document is used. As an FYI, I have decided 
> to proceed 
> with consecutive page numbering through the whole book.
> 
> Next, I have a style question:
> 
> I need to make frequent reference to submenu commands. As an 
> example, if I 
> wanted to tell someone how to set up their page numbers in a 
> FM document, I 
> might direct them to "Select Format > Document > Numbering" and then 
> proceed with an explanation of the resulting dialog.
> 
> I know that it may be better to say something like, "From the 
> Format menu, 
> select Document, then select Numbering," but this gets to be 
> very tedious 
> for both me and the reader when a procedure/chapter requires 
> this kind of 
> direction on a frequent basis.
> 
> This problem permeates the entire suite of documentation at 
> my client's   
> site.
> 
> However, the problem is that almost every tech writer that 
> has been there 
> has adopted a different style for specifying these multi-level menu 
> selections.
> 
> I have been given the task of cleaning up their templates and 
> style guide 
> and this has me stumped as to how to approach it.
> 
> I have checked the various "popular" style guides, but none 
> of them address 
> this technique (and most seem not to even consider it an option).
> 
> Are we wrong? Should we bite the bullet and adopt the verbal 
> approach of 
> describing how to navigate the menus?
> 
> If anyone else uses this "shorthand" approach, can you give 
> me some idea as 
> to the style(s) you have adopted? I am particularly 
> interested in hearing 
> what character you use to separate the multiple levels of menu 
> commands/options.
> 
> Hope this makes sense....
> 
> Thanks in advance ..
> 
> Ada Lai
> 
> 
> _________________________________________________________
> Do You Yahoo!?
> Get your free @yahoo.com address at http://mail.yahoo.com
> 
> 
> ** To unsubscribe, send a message to majordomo@omsys.com **
> ** with "unsubscribe framers" (no quotes) in the body.   **
> 

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