Book? Or books?

Subject: Book? Or books?
From: MList -at- chrysalis-its -dot- com
To: "TECHWR-L" <techwr-l -at- lists -dot- raycomm -dot- com>
Date: Thu, 24 Apr 2003 11:43:22 -0400


The question is how far to go in separating certain
kinds of material into narrow-purpose documents, as
opposed to keeping disparate stuff in a more general-
purpose (big) document.
Assume there are, and will continue to be, a separate
(throw-away) Install Guide, a separate (keeper) Setup Guide,
a separate (keeper) User Guide, and a separate (keep, throw,
whatever) Release Notes.

Assume that the User Guide has a big chapter on Integration
instructions for using our stuff with various third-party
applications, but you use the relevant portion of that
chapter one time, and then never look at it again...
unlike the rest of the User Guide that is usefully kept as a
reference. If you've bought the SDK to do your own
development, then you don't ever refer to the "canned"
integration instructions.

Would it make sense to anybody to separate that Integration
stuff out into its own document -- with four-and-five-
page chapters per third-party app? It doesn't get used
until after you've done Installation and Setup. It's
relatively self-contained. It's also not printed (nor is
the User Guide where it currently lives), but is merely provided as a PDF.

Similarly, we have added Java support. I was thinking of
making that a separate, small document, as well. The
files required for Java are provided on the Client CD,
because they are needed whether you are writing your own
Java stuff, or have a third-party Java app with which you
want to integrate. We don't have any ready-made Java
integrations.

Advantages to this approach seem to be that you only
use the documents that are relevant to you, and you
don't have to print out a honkin' big single document
where you'll never even look at whole chapters.

Disadvantages seem to be that some people might need
to refer to several documents while getting going.
Others might not.
Either way, the text will tell you where you need to go next,
and it will be obvious what each document is for.

Basically, I want to keep together the stuff that feels like
it belongs together, and break off stuff that looks like
it can live separately, without introducing an infinite
proliferation of separate docs.

Thoughts?

/kevin

^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Last chance to order RoboHelp X3 and receive a $100 mail-in rebate,
PLUS free RoboScreenCapture and WebHelp Merge Module. Offer expires
4/30/03! Order here: http://www.ehelp.com/techwr-l

Help celebrate TECHWR-L's 10th Anniversary starting this month!
Check out the contests at http://www.raycomm.com/techwhirl/special/contests/
Happy birthday to you, happy birthday to you, happy birthday TECHWR-L....

---
You are currently subscribed to techwr-l as:
archive -at- raycomm -dot- com
To unsubscribe send a blank email to leave-techwr-l-obscured -at- lists -dot- raycomm -dot- com
Send administrative questions to ejray -at- raycomm -dot- com -dot- Visit
http://www.raycomm.com/techwhirl/ for more resources and info.



Follow-Ups:

Previous by Author: RE: certification
Next by Author: RE: On PDFs
Previous by Thread: RE: Diagramming databases with Visual Studio 6
Next by Thread: Re: Book? Or books?


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


Sponsored Ads