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.
Subject:Re: Updating User Docs From:"Jeanne A. E. DeVoto" <jaed -at- BEST -dot- COM> Date:Thu, 30 Apr 1998 23:10:08 -0700
At 3:36 AM -0700 5/1/98, Gita Jayaraj wrote:
>I have to write a user doc. for old users of our software who will be =
>requiring only upgrades. Both my boss and I feel that it doesn't make =
>much sense (nor is it economical) to give them the complete new user doc =
>as only enhancements have been done (on the software) and almost all the =
>information they have (in the old user doc) is still valid.
> What we basically need to tell them is about these enhancements. How do =
>I go about it?
What you need to write is usually called a "What's New" document. This
document describes the new features and enhancements and can be kept with
the original manual for reference. It's used when the changes to software
are more extensive than can be covered in a Read Me, but not extensive
enough to justify a new user doc.
How to organize it depends on how much new stuff there is to document. If
there are only a few new items, it's easiest to arrange them in some
functional grouping (for example, "Printing Enhancements", "Graphics
Enhancements", and so on).
If the document will be long enough that flipping through it may be
time-consuming, you may want to mirror the structure of the original
document: for each section of the user doc, write a corresponding chunk to
describe the enhancements pertaining to that original section. In this
case, you may want to also include an updated index, with references to
both the original document and the What's New; that way, users can look in
just one place for information.
At a certain point, the improved usability of a single document starts to
outweigh the expense of shipping a new user doc. My own rule of thumb for
this is that when a What's New document approaches 10% of the user doc,
it's time to start thinking about folding the What's New into a new user
doc version. (Of course, your mileage may vary on this point.)
--
jeanne a. e. devoto ~ jaed -at- best -dot- com http://www.best.com/~jaed/
Morning people may be respected, but night people are feared.
