TechWhirl (TECHWR-L) is a resource for technical writing and technical communications professionals of all experience levels and in all industries to share their experiences and acquire information.
For two decades, technical communicators have turned to TechWhirl to ask and answer questions about the always-changing world of technical communications, such as tools, skills, career paths, methodologies, and emerging industries. The TechWhirl Archives and magazine, created for, by and about technical writers, offer a wealth of knowledge to everyone with an interest in any aspect of technical communications.
Subject:Re: Choosing a menu option From:Jim Purcell <jimpur -at- MICROSOFT -dot- COM> Date:Thu, 14 Aug 1997 09:57:37 -0700
> Buck wrote:
>
> > This thread demonstrates a perfect case for standardization in
> > documentation. The many opinions and statements such as, "I do
> this,
> > because..." make those of us who are dedicated to standardization
> quiver
> > (shiver? tremble? shrug?).
>
> David Girardot ripostes:
>
> I don't think it makes a big difference as long as there is sound
> reasoning for a style, the style is consistent across the documents
> you produce, and you're doing it all for the reader.
>
Advocates of "Choose X from the Y menu" usually argue that the
introductory prepositional phrase in "From the Y menu, choose X" weakens
the sentence. If it does, it does so in the interest of clarity. In
addition to naming the objects in the order the user sees them (menu
first, then command), this syntax puts the modifier "from the Y menu"
next to the thing it modifies ("choose"). It is not, of course, the only
way to write a sentence, but it frees the reader from pondering, even
momentarily, what she is supposed to do.
> I think that standardization can go a bit too far. If you
> micro-manage style, like anything else, you end up with a lot of
> busywork that IMHO is often not worth the paper it's printed on. A
> friend works at a shop where the lead editior does this. Each week
> he comes out with a list of pronouncements like "From now on we will
> write 'click the OK button' instead of 'click OK.'" What a waste of
> ink.
>
I refer to David's earlier statement: "I don't think it makes a big
difference as long as ... the style is consistent across the documents
you produce ...." The lead editor here is doing exactly that: defining
and enforcing consistency across documents. It's what lead editors do.
If the writers prefer "Click OK," they should gang up on the editor and
make that the standard. But you do need a standard.
> On the other hand, I've worked on projects where the writers
> took the time to use the proper terminology for things like dialogs,
> menus, toolbars, and the trainers didn't.
>
And to be fair, I'll bet some trainers could point to times when the
writers were slack about this.
<snip>
> The key to effective writing is to consider
> the reader, whether you write manuals, essays, or short stories.
>
No argument here, but realize that nitpicky editors and style mavens
might also be concerned for the reader.
Jim Purcell mailto:jimpur -at- microsoft -dot- com
My opinions, not Microsoft's
TECHWR-L (Technical Communication) List Information: To send a message
to 2500+ readers, e-mail to TECHWR-L -at- LISTSERV -dot- OKSTATE -dot- EDU -dot- Send commands
to LISTSERV -at- LISTSERV -dot- OKSTATE -dot- EDU (e.g. HELP or SIGNOFF TECHWR-L).
Search the archives at http://www.documentation.com/ or search and
browse the archives at http://listserv.okstate.edu/archives/techwr-l.html
