Writing user's guide for an add-in?

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
that it is only a pernicious, Pythagorean coincidence." George Miller, "The Magical Number Seven" (1956)

Previous by Author: Summary Re-Post: Should my ego be squashed?
Next by Author: E-mail vs. message?
Previous by Thread: Re: Programmer/Writer?
Next by Thread: Summary - Easter Egg Recognition

What this post helpful? Share it with friends and colleagues:

Sponsored Ads

Sponsored Ads