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:Writing user's guide for an add-in? From:"Geoff Hart" <Geoff-h -at- mtl -dot- feric -dot- ca> To:TECHWR-L -at- lists -dot- raycomm -dot- com Date:Thu, 30 Sep 1999 14:33:04 -0400
Dal Gemmell is <<...writing a user's guide for an add-in
application... The larger application's user's guide is being
written by another company. I have the rough outline for the
larger application's user's guide, but I cannot wait for them to
finish writing their manual before starting mine. The add-in
application is actually quite a large application in its own right
and duplicates a lot of the larger application's menus,
toolbars, dialog boxes, interface, etc.>>
It wouldn't make much sense for you to duplicate most of the
manual for the other application, but filling your manual with
cross-references to the other manual could be even worse; it
would drive me nuts, and I bet I'm not alone in this. If you
need to cross-reference, keep it to a minimum (only where it's
absolutely necessary), and consider repeating relevant
information in your add-in's manual rather than telling readers
to look elsewhere.
My initial reaction to the problem is to assume that the users
of the add-in must already know how to use the main
application; in that case, you can focus solely on the new
aspects that your add-in provides and ignore the rest. That's a
very big assumption, and you should confirm it with someone
who knows your audience well before committing to that
approach; for example, if the add-in is the only application
users ever see (i.e., it forms a new interface to the underlying
application), not telling them about the functions of the main
application may prevent them from using much of the add-in.
In that case, users may really need a fair bit of repetition of
material from the other manual for the add-in's manual to be
effective. If you're lucky, you can simply get the other writers
to send you this information so you can rewrite it to fit your
own style.
--Geoff Hart @8^{)} geoff-h -at- mtl -dot- feric -dot- ca (Pointe-Claire, Quebec)
"Perhaps there is something deep and profound behind all those sevens, something just calling out for us to discover it. But I
suspect
that it is only a pernicious, Pythagorean coincidence." George Miller, "The Magical Number Seven" (1956)
