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:Documentation Likes and D From:Barb Philbrick <barb -dot- philbrick -at- PCOHIO -dot- COM> Date:Mon, 11 Jul 1994 17:10:00 -0500
K>At WordPerfect we're doing research to try and see what is and isn't
K>useful in our printed and online documentation. What in the
K>documentation is valuable to you and what could be thrown out? For
K>example, is the glossary useful? Would anyone complain if we pulled
K>it out? Would it help to reference online from printed or printed
K>from online? What type of information do you expect to find online?
K>What type of information do you expect to find in printed?
I like glossaries. For word processing and desktop publishing programs,
I like to see general typesetting terms defined, as well as program-
specific terms. Because I work in a number of different word processors
and desktop publishing programs, I like to see terms that mean the same
thing as those in other packages defined (for example, tag = style).
I expect to find everything online. I'm one of those weirdos that likes
online help (if you saw my desk, you'd understand why). I don't need to
see online help stuff cross referenced to the hardcopy, though (unless
there's no index). Hard copy cross references are especially annoying if
the information is exactly the same.
I don't have WordPerfect documentation, so I can't comment specifically
on it, but here's some of my beefs from other manuals:
-Too simplistic. Don't assume I'm an idiot. Go into some depth on
features that are a somewhat complicated.
-Too advanced. Don't assume I was born with knowledge of your package,
either. It's been a while, but last time I used WordPerfect I had to use
the mailmerge function, and the text baffled me. I don't remember
specific problems, but I think it was because it assumed I knew things
that I didn't.
-Include items that are listed in the table of contents items in the
index. I rarely use the table of contents, but use indexes a lot.
-Don't ballyhoo features. They usually aren't as easy as the text says
they are. Just tell me. Example of this: In Word 6, they extol the
virtues of the Master Documents features. This feature doesn't work for
the documents I do (Microsoft assures me that they're working on it). It
is incredibly annoying to read about how great this feature is when I'm
waiting 20 minutes to find out this great feature hung up my system.
-This one's harder to do (and maybe requires a separate manual or a
third-party book), but I wish manuals compared features and terminology
more. For example, I use Ventura and Framemaker. I wanted to outdent
(Ventura's terminology) headings, but Frame didn't have an obvious way
to do this. I called technical support to find that everything else has
to be indented in order to create an outdent. Not a big deal; should
have been obvious; but I was still in Ventura-mode, and tried to attack
the formatting like I would have in Ventura.
-I use manuals as a reference; I don't read them straight through. Don't
count on the fact that I've read something in an earlier chapter that's
going to make this chapter crystal clear. (This is probably one of the
reasons I like online help so much - online help doesn't normally assume
anything about what you've read before.)
Hope this helps -
* CMPQwk 1.4 #9107 * If love is blind, why is lingerie so popular?