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.
>>> kevin wrote awhile ago
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, ... 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?
Similarly, we have added Java support. I was thinking of
making that a separate, small document, as well.
We went through this discussion recently for our products,
and we decided that the standard set of documents should
be kept together, while stuff beyond the basics should be
housed in a separate document.
Several reasons we went this way. Keep the as-designed
material together should provide a relatively stable set
of docs, less maintenance for writers, more consistent
contents for customers. Material that stretches past the
original intent is more dynamic, and would need to be
updated more often as additions, changes, more advanced
topics and uses are found. These don't change the initial
set of material, but extend it. Keep this stuff separate.
The stuff you describe is beyond the basics, not something
likely to be needed on the initial install, so they shouldn't
need any of it on-hand. This material is such that people
would actively seek it out, and as such they would only need
a targeted portion of it. If it's likely that customers would
only need one of the Integration material, separate document,
if they would likely need several, group them in a book, but
still keep it separate from the basic documentation.
CB - way behind on digesting
smaller is better,
when it comes to docs
Surfy! http://www.surfy.net Great web search, free web email, and $9.95 unlimited Internet access
Powered by Outblaze
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
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.