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:Command nomenclature From:"Andrew F. Swartz" <aswartz -at- HARLEQUIN -dot- CO -dot- UK> Date:Mon, 9 Jun 1997 16:50:22 +0100
I did a small survey of my company's users (mostly police officers) and
found that over half didn't understand the convention Yvonne DeGraw
suggests: "Choose File-->Open." However, we explain the convention only in
the preface, and I suspect not many readers look at prefaces. I look
forward to trying Yvonne's suggestion of explaining the convention on first
use of each chapter. Since this is one of the most common sorts of
instructions in a software user manual, it seems like it's worth taking the
time to figure out the best wording.
I have no major quibble with MS's recommendation
> On the File menu, click Open.
> From the File menu, choose Open.
for standalone sentences, but it's difficult to think how to use that
recommendation when it's part of a bigger sentence, such as 'To open a
file, from the File menu, choose open.' I prefer to word a sentence like
that as 'To open a file, pull down the File menu and choose Open.'
Best wishes,
--Andrew Swartz
----------
> From: Yvonne DeGraw <yvonne -at- SILCOM -dot- COM>
> To: TECHWR-L -at- LISTSERV -dot- OKSTATE -dot- EDU
> Subject: MS Manual of Style, disagreements with
> Date: 09 June 1997 16:34
>
> Bev Parks wrote:
> >It is quite possible that not all people want to be Microsoft zombies.
> >There just *may* be a better way out there. Maybe someone at Microsoft
> >made a poor decision. It could happen.
>
> I now use the MS Manual of Style for most things. But I've found several
> places where I disagree. Here's my pet disagreement...
>
> MS says for menu commands, use one of these (File & Open are bold):
>
> On the File menu, click Open.
> From the File menu, choose Open.
>
> An alternative I've used and gotten excellent user feedback on is:
>
> Choose File-->Open.
>
> (File-->Open is bold and --> is a Wingding character or an image.)
>
> In the preface and on first use (maybe first use in each chapter
depending
> on the manual structure), I explain this style. I've found that users
> internalize it either without an explanation or after the first
explanation.
> For less-experienced audiences, I've also used:
>
> Choose the File-->Open menu item.
>
> Users say they like this style because they can easily skim for menu
> commands in a set of steps. Users and customer support at companies where
I
> use this style commonly start using it themselves in e-mail messages and
bug
> reports.
>
> Perhaps many people think about choosing menu commands as one action, and
> this supports that thought mode. (They choose Open, and File happens to
be
> the place where that is located.)
>
> Also, describing cascading menus is less cumbersome. "Choose
> Edit-->Sort-->By Name" is a natural extension.
>
> Of course, all I have is anecdotal evidence. I don't have any studies to
> back up the advantages of this style. And, since it isn't currently
> standard, it depends on your audience and your client.
>
> If MS used this style it would become familiar to all users and the
> advantages would be even greater. Anyway, if you like this idea, feel
free
> to use it. I've seen others use it successfully, too. I'd love to see
this
> style become more common so I could use it with more clients.
>
> P.S. This isn't a Microsoft/Gates flame. If you can't beat 'em, buy their
> stock. I've bought more MS stock than software over the years.
>
> P.P.S. My other disagreements the MS Manual of Style are "email" vs.
> "e-mail" and "Select the XXX check box." I prefer to spend a few extra
words
> to "Put a check mark in the XXX box."
> Yvonne DeGraw, Technical Services o Technical Writing
> yvonne -at- silcom -dot- com o Online Help
>http://www.silcom.com/~yvonne o Web Documentation
> Tel: 805/683-5784 o Database Publishing
> Chair, STC Region 8 Conference: http://stc.org/region8/snb/reg8conf
> Santa Barbara, CA Call for Presentations deadline is June 30.
>
> 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
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