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: Reasons for online From:Glen Accardo <glen -at- SOFTINT -dot- COM> Date:Tue, 20 Dec 1994 16:06:36 -0600
> Glen, Are you users pleased with your indexes? I'd be surprised if they
> were . . . (I'm responding to you personally because I don't want this
> to be perceived as a slam. My question is sincere.)
Yes, they are. And no, you'd have to do a lot more than that for me to
consider the question a slam.
Let's look at a couple of "principles" of tech writing. Rule number one
according to a gazillion experts is "consistency." I agree. If write a
section on frobbing snobnitzes, I must use the word "frob" when I mean frob.
If I also use "blork," "scrludz," and "plurquey" to mean the same thing
as "frob," I wrote poorly. Granted, English gives us far too many synonyms,
and sometimes we aren't perfectly consistent, but hey, no one is asking
for perfection. But, we generally do try -- just look at the number of
people trying to sort out "choose," "click," and "select."
Rule number two could be something like "make it easy to find." How far do
we take this? If I used the word "frob" in the text, why include the others?
True, I should have entries like:
This allows people to search for frobbing and snobnitzes and get to the
information. I've had some entries posted in four or five places. But,
I am completely opposed to idiots who think I should have used the word
"blankelquartchen" and insist that I rewrite the manual so that they
can find things.
If I give someone the ability to find any word in the text, what else can
they look for?
glen accardo glen -at- softint -dot- com
Software Interfaces, Inc. (713) 492-0707 x122
Houston, TX 77084