Best practice for Edition or Revision history?

[Geoff Hart <ghart -at- videotron -dot- ca>]

Tammy Lloyd wondered: <<Is there a standard limit for edition or 
revision histories? >>

Not that I'm aware of. But I'd say that the "best practice" would 
involve thinking carefully about what you intend to achieve by 
providing this information.

<<In each preface, we include an Edition History in which a 
comprehensive list of the document's editions are listed. For each 
edition, the edition (e.g., First) and its part number, the product 
version the document accompanies, and the major changes that were made 
to the document are included in a table format. Some of our documents 
are now reaching more than ten versions, which is taking up nearly a 
page in the Preface.>>

In the popular press, where the goal of such histories is to brag about 
how well your book is selling or demonstrate that it's been successful, 
revision histories can be moderately extensive. That probably isn't 
your context, but if it is, consult the Chicago Manual of Style for 
guidelines. In CMS 14, you can find this under "Publishing History 
(beginning at 1.20) and "Prior publication" (1.33).

For technical manuals, the goal of these pages is primarily to answer 
the question "am I using the correct version of the manual for the 
software that I have installed?" That's useful for those few people who 
ever consult the revision history; most of us just ignore it. But to 
address that primary need, you need some way to tie the revision 
history to the actual software releases for those who need this 
information.

What software releases are still out there being used? Which of these 
does the current manual support fully? Once you can answer those 
questions, you can figure out how many revisions to include. For 
example, if the software went from version 1.5 to version 1.6 and 
changed so much that some aspects of the old manual were deleted and 
some new aspects were included, then the revision history should 
reflect this. That's a significant change to the reader.

In contrast, if you went from version 1.5 to version 1.51 and all that 
changed was a few bug fixes that didn't affect the documentation, 
there's no need to reflect this in the revision history. Similarly, if 
you revised the manual to make a procedure clearer, but didn't actually 
change the content of that procedure, there's no need to include this 
in the revision history. Neither change is sufficiently significant 
from the reader's perspective to merit a mention. Contrast this with a 
"pre-release" manual full of typos and errors, and the "post-release" 
follow-up manual, which contains exactly the same content but with the 
typos and errors fixed: that requires a mention.

<<If we omit the oldest document versions, is it necessary to reference 
them in some way so that users know there are even later versions of 
the document?>>

Only in the following sense: "Revision 1.5 of this manual covers 
versions 1.5 to 1.57 of the software. For previous versions of the 
software, consult earlier revisions of the manual." (No need to list 
revisions 1.1, 1.2, 1.2.2, etc.) If you have some control over what 
goes on your Web site, you could present a comprehensive revision 
history there, with links to PDFs of the old versions. That's 
value-added!

--Geoff Hart   ghart -at- videotron -dot- ca
(try geoffhart -at- mac -dot- com if you don't get a reply)


^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

ROBOHELP X5: Featuring Word 2003 support, Content Management, Multi-Author
support, PDF and XML support and much more!
TRY IT TODAY at http://www.macromedia.com/go/techwrl

WEBWORKS FINALDRAFT: New! Document review system for Word and FrameMaker
authors. Automatic browser-based drafts with unlimited reviewers. Full
online discussions -- no Web server needed! http://www.webworks.com/techwr-l 

---
You are currently subscribed to techwr-l as:
archiver -at- techwr-l -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.