Summary of Writing an Add-In Application's User's Guide...

["Gemmell,Dal" <Dal_Gemmell -at- email -dot- syscom -dot- com -dot- tw>]

Due to popular demand, here is a summary of the postings I received plus my
original post. Thanks again to the people who took the time to respond:

Pete Haberson wrote:

"I've done this several times, and it always seems to be difficult. The way
I've found most successful (for me, at least) is to come up with the outline
for the user's guide by focusing on the tasks the user performs and ignoring
(at this point) the distinction between the add-in and the larger app. After
I have a very rough draft, I try to identify tasks that are entirely or
predominantly performed in the larger app. For those tasks, I document the
basic, most likely, or default procedure, and refer the user to the other
manual for more in-depth information.

For example, let's say printing is handled by the larger app. (This is
actually a pretty good example, since apps usually rely on the OS and the
driver for a particular printer.) I'd explain that you can print a document
by choosing "Print" from the "Foo" menu, then specifying number of copies
and clicking "Print" in the dialog box that appears. THEN I'd say that there
are more choices you can make in regard to printing, and for more
information about them, see the "Bar" manual.

I just basically try to balance the value of providing information in one
place against the cost of replicating information unnecessarily."

Gilda Spitz wrote:

"Yes, our company created an add-in for Microsoft Excel. I did exactly what
you mentioned.
In the Introduction, we indicated that we assumed our users knew how to
perform most Excel tasks, and referred users to the Excel documentation.
Then we described the add-in's new functionality,

However, as an added twist, there were several relatively obscure Excel
tasks that were important to know in conjunction with our add-in,
and we weren't sure that an average user would  be familiar with them. So
we added a brief description of each in an appendix entitled "Related
Excel features", with an explanation of why they were particularly useful,
and with  instructions to look at the Excel documentation for further
details.
This was a bit awkward, but it worked."

Donna Fisher wrote:

 "Part of your decision should be based on who your user will be and how
much they will know about the primary application.  That said, how about
including a section at the front of your add-in application guide that
summarizes the parts that you need to reference in the rest of your
document?  Then the primary app stuff is not in the way of your add-in
documentation, but is still available to you?

I know that that means more work for you, but it also frees you from
depending on the primary application documentation written by someone
else."

Geoff Hart wrote:

"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."

My original post:

"I have a problem that I am hoping some of you seasoned veterans can help me
with.

I am writing a user's guide for an add-in application. Although both the
add-in application and the larger application are currently being developed
by my company, 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.

My original idea for writing this user's guide was focusing on the add-in
application's extensions and referring users to the other manual to perform
the majority of the functions. For example, "Creating a Project" is
something you can do using both applications. However, this will result in
far too many references to the other manual. Has anyone written this type of
manual before? 

Any help would be greatly appreciated."

Regards,

Dal

dal_gemmell -at- email -dot- syscom -dot- com -dot- tw