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: Style Manuals From:"Barbara A. Tokay" <batokay -at- IX -dot- NETCOM -dot- COM> Date:Wed, 3 Feb 1999 14:03:42 -0500
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
> Marie C. Paretti, PhD
> Recognition Research, Inc. (RRI)
> 1750 Kraft Drive, Suite 2000
> Blacksburg, VA 24060
> mparetti -at- rrinc -dot- com
> From ??? -at- ??? Sun Jan 00 00:00:00 0000==