RE: Release notes: what's your standard like?

[mlist -at- safenet-inc -dot- com]

Jenn Wilson wondered out loud:

> I'm curious how your respective organizations view and 
> publish release 
> notes.
> 
> Most of the software companies where I've worked have used them in a 
> pretty typical format:  a list of bug fixes, known issues, 
> workarounds, 
> and (depending on the standard at hand) installation 
> instructions.  Once 
> in a while, the document would include a quick overview of 
> major changes, 
> but for the most part, granular instruction was left to the standard 
> documentation set.  A set of release notes was included with 
> any release.

That pretty much describes what we (I) do.

There's a quick blurb to describe the product (since we have several in the
product line that I cover). 
Then there's a table listing supported platforms by release.
In other words, it shows historical and current info... basically just a
list of OS versions down the side and a list of product versions across the
top, and a check-mark (or not) where they intersect.

Then, a table or two showing how our product bits go together:
 - system software version
 - system firmware version (s)
 - associated peripheral device f/w version(s)
 - client software verion
 - SDK version

For example, sometimes a system software version can be used with two or
three system firmware versions, or a client software version is fine with
several combos of system innards, and so on. We only update the SDK when
there's new API to document, so a version will co-exist with several changes
of HW and SW and FW.

If appropriate, there'll be a note saying why a given firmware or software
version exists, especially if it's older than the most current. Usually,
there're a couple of minor revisions between the current version that's been
sent for (and received) FIPS approval, and the next one. We let the customer
know that they have the choice... either stay with version x.x because your
policies require you to use FIPS-validated systems, or use the newer
not-yet-evaluated version in order to get newer fixes or features, but
forego the official validation.  

Then we have a point-form list of new features (if any, or it might just say
"several fixes, detailed in the next section").  As somebody else mentioned,
lengthy explanations of new features belong in the main documentation (which
is WebHelp).

Then it's a table of "Known Issues", with the associated tracking ticket
number, a status, and a paragraph or three of description, with a
work-around suggestion, and a gormless statement like "to be addressed in a
future release".

And finally a table of "Addressed Issues" - we cover only "addressed with
this release". If you want a bug/issue history, get previous versions of the
release notes.

The Customer Release Notes are published as a PDF that lives on our Support
Web site. You can't browse to it. Instead, if you have our documentation CD,
there's a link to the "Customer Release Notes".

My next hope is to have the entire Help system on the web site. You get a
valid-at-release-time set of Help on the CD, and you can update with fresher
Help from the web-site.  That will be useful only for our more mature
products... the newer ones turn over too quickly.

There. I've told you more than I know on the topic.

Kevin

The information contained in this electronic mail transmission may be privileged and confidential, and therefore, protected from disclosure. If you have received this communication in error, please notify us immediately by replying to this message and deleting it from your computer without copying or disclosing it.

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

Try WebWorks ePublisher Pro for Word today! Smooth migration of legacy
RoboHelp content into your new Help systems. EContent Magazine Decision-
maker review (October 2005) is here: http://www.webworks.com/techwr-l

Doc-To-Help 2005 converts RoboHelp files with one click. Author with Word or any HTML editor. Visit our site to see a conversion demo movie and learn more. http://www.componentone.com/TECHWRL/DocToHelp2005

---
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- techwr-l -dot- com
Send administrative questions to lisa -at- techwr-l -dot- com -dot-  Visit
http://www.techwr-l.com/techwhirl/ for more resources and info.