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