Re: Style Manuals

["Barbara A. Tokay" <batokay -at- IX -dot- NETCOM -dot- COM>]

I believe the issue here isn't what certain elements are called but whether
technical writers are communicating clearly about how a software package is
used! Too many "help" systems--on line, off line, in the box, out of the box,
in the manual, on the CD-ROM, on the floppy--are simply laundry lists of
"elements." As in: "Click [on] the help button." "Did that answer your
question?" "Sorry, there is no further information about this topic available.
For additional information, please  purchase the $1 fax-by-the number service
or the $2 million telephone unhelpful service..."

Does this list ever address this sort of real-life issue--as in, how to
document a poorly designed, malfunctioning software package?



Marie C. Paretti wrote:

> I have to agree (not for the first time!) with John Posada and Lisa Comeau
> on this one. As I've said before, what's important in all of this too me is
> the user - the person who reads the manuals I write. My goal is not to
> reinvent the wheel but to use terminology that they are familiar with and
> make what I write as easy to understand as possible.
>
> When I'm teaching grammar, I call that dot at the end of sentence a period.
> Why? Because that's what the people who wrote the handbook call it. When I
> give someone directions to my house, I tell them to turn on Ardmore Street.
> Why? Because that's what the people who planned the town chose to name the
> street I live on. When I want my users to select a choice from a list named
> File at the top of their application, I say "From the File menu, choose..."
> Why? Because MS (or someone - don't really care who) named those lists
> "menus" and that's how my readers think of them.
>
> Language is a set of *agreed upon* terms (sounds/symbols, etc.) that refer
> to objects/concepts/etc. Grammar is a set of agreed upon rules for
> combining those terms into coherent syntactic units. You can make up your
> own terms, and your own grammar (James Joyce, anyone?), any time you want,
> but that may not be in your reader's best interest.  On the other hand, MS
> (or any other software manufacturer) does not control everything. If I
> think their term is confusing and I have a valid reason for using a
> different one, I do.  But *only* if I have a valid reason.
>
> People on this list refer questions to the MS Manual of Style when those
> questions are about common terms used to describe user interface behavior
> on software that runs under MS operating systems. Why? Because MS has names
> for lots of things that appear on such user interfaces, and they've set up
> a common way of describing and talking about them.  Strunk and White, the
> Chicago Manual of Style, the MLA Handbook, the McGraw-Hill Handbook for
> Writer's, Diane Hacker's A Writer's Reference, etc. etc. (I own lots) do
> not, anywhere, tell me what differentiates a screen from a window from a
> dialog box. Nor do they tell me whether to click or click on a button. The
> MoS provides me with a baseline standard for those things. Do I always use
> it? No. But then again, I split infinitives long before the OED declared it
> acceptable.
>
> Marie
>
> Marie C. Paretti, PhD
> Recognition Research, Inc. (RRI)
> 1750 Kraft Drive, Suite 2000
> Blacksburg, VA 24060
> mparetti -at- rrinc -dot- com
> http://www.rrinc.com
>
> From ??? -at- ??? Sun Jan 00 00:00:00 0000==

 From ??? -at- ??? Sun Jan 00 00:00:00 0000=