Re: Command nomenclature

[Beth Thomerson <thomerson -at- BGS -dot- COM>]

Hi,

I'm new to the list, but have enjoyed the give & take I've seen over
the past week or so.  I thought I'd contribute an opinion on the
command nomenclature discussion.

On  9 Jun 97 at 16:50, Andrew F. Swartz wrote:

> 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."

Andrew, it makes sense that over half of your test audience didn't
understand the Choose File-->Open convention, especially if you just
printed out a sample procedure to show, and each person didn't look at
the procedure while he or she could compare it to the actual
software. However, we have to hope that those savvy users who
actually read the manual (it could happen! ;- ) ) might wonder for a
flash what  it means (if they *haven't* read the preface or
convention section), but most people who open manuals have software
up and running. It would probably take only a moment before they
realize what it means. It's a fairly intuitive way to handle commands
without being overly wordy, since most s/w programs use the
similar/same words on menus (File, Edit, Window, Help, etc.).

>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.

You may be right that not many readers look at prefaces, at least
initially.  I know I'm guilty of opening a s/w manual, immediately
begun with procedures, found something that I didn't understand and
THEN turned to the convention/preface section.  However, as
technical communicators, it's important to remember that people
read manuals for different reasons, and people learn/absorb info
different ways. That's one reason why there's never ever going
to be a perfect manual, since everyone has opinions, and no one way
of instruction is perfect for everyone.

That's one reason why I *don't* like to explain a convention the
first time I use it in a chapter. Instead, I might put a small note
in the margin that says something like "If you're new to this
product, please read Chapter 3, "Basics" first. This chapter provides
concept and convention information that will help you come up to
speed fast."

Of course, every writer knows his or her audience better than an
"outsider looking in", and I'm not presuming to preach. I just
believe that we can creatively look for ways to gently nudge the
reader to go the right places first, before he or she gets lost,
calls technical support in a tizzy, and hates all software manuals.
However, there are many ways of structuring a manual so that we can
ensure lost readers can find their way to the right spots by using
task-oriented headings, providing a complete index with a lot of soft
terms, etc. It we are constantly explaining conventions every time we
use them, we end up with a lot of redundancy.  Just my thoughts on
this...sorry to be so wordy my first time out of lurk mode!

Beth


 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
>

"No matter where you go, there you are"

Beth Thomerson (Thomerson -at- bgs -dot- com)
BGS Systems, Inc.
(617) 663-4612 phone, (617) 890-0000 fax

 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