Re: Revision Numbers (#669722)

[wburns -at- MICRON -dot- COM]

Rebecca writes:

>When I integrate new version changes into the manual, she would like to
>include change bars (revision marker in the margin) to show where the
>change has taken place in the manual. Next to the change bar, the
>software version number would appear, so that you would have an exact
>record of when the change was implemented. I don't mean she wants these
>changes for SME reviews. She wants the CUSTOMER to get the final draft
>of the manual WITH CHANGE BARS so that the customer can see the new
>features.

I'll try to address your other question as well (concerning release notes). We
don't write commercial documentation here, so this may not help either way.

The majority of our documents are written in HTML and delivered using an
intranet. When we make changes to a document, we use boldface to highlight
passages that have been revised, we write a detailed revision delta to explain
what changes have taken place (going as far as comparing specific parameter
changes), we provide hypertext links between the delta and the individual
changes, and we mark each affected section in the TOC with a "revised" tag. We
have trained our employees to look at the delta (or document history) when they
are notified of changes.

In our environment, we have to communicate changes in information as simply and
directly as possible. If employees have to read an entire document to know what
has changed, they won't bother. If they have to guess what has changed, they get
confused and stop using the documents.

In a manufacturing environment, knowing the date of a change in software can be
crucial to tracking quality data. The company should have mechanisms in place to
track equipment hardware and software changes. If they only use the manual to
keep track of this, then they may not be tracking their maintenance information
very effectively.

I think it makes more sense to leave the software version information with the
release notes. Adding it into margins or what not will just provide more visual
noise. Unless the plan is to remove that information after the subsequent
revision, you're eventually going to have margins brimming over with revision
information. If those release notes provide a point-by-point description of the
changes, then the amount of searching your customers will have to do to find
documented changes will be minimized. The references to pages numbers will also
help because the users will be able to put the information into a context. (I
wouldn't underestimate the value of the latter.)

>Has anybody released books with change bars? How did customers react? Is
>this, in fact, a requirement for ISO9000? Do you feel that same gut
>feeling as I, that this isn't going to be useful in the long run?
>

ISO requires that you be able to notify users about changes to written
information that affect how they do their jobs (more or less). They don't
stipulate HOW to do this. You do need to be able to distinguish the current
version of a document from an earlier version (whether you use a version number
or a revision date) and have procedures in place for replacing outdated
material. I know from experience that the methods we use are considered
acceptable. Whether it's preferrable is another matter.

Bill Burns
Assembly Documentation Supervisor
wburns -at- micron -dot- com
-----------------------------------------
This message brought to you by W.A.S.T.E.
and your local potsmaster.
-----------------------------------------

 TECHWR-L (Technical Communication) List Information: To send a message
to 2500+ readers, e-mail to TECHWR-L -at- LISTSERV -dot- OKSTATE -dot- EDU -dot-  Send commands
   to LISTSERV -at- LISTSERV -dot- OKSTATE -dot- EDU (e.g. HELP or SIGNOFF TECHWR-L).
  Search the archives at http://www.documentation.com/  or search and
browse the archives at http://listserv.okstate.edu/archives/techwr-l.html