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

["Tom Storer" <tstorer -at- free -dot- fr>]

>Jenn Wilson said:
>
>I'm curious how your respective organizations view and publish release 
>notes.

I work at a large company with development and management teams in multiple
time zones. We have the standard content you described: known issues and
workarounds, brief explanations of "by design" but potentially unexpected
behaviors ("that's not a bug, it's a feature"). We used to have a list of
bug fixes, by customer bug number, but we no longer have that, for the
ridiculous reason that when we acquired a large competitor a couple of years
ago, we adopted their bug-tracking system, and no provision was ever made to
track customer-reported bugs! They're working on it, but the wheels of
process grind exceeding slow. New features do not go in the release
notes--we have a separate "What's New" guide. Nor does anything that is
fully covered in the documentation itself, although dev teams regularly want
to repeat certain things in the release notes on the grounds that they are
"important." We resist that.

It's the release-note compilation and publishing process that interests me.
We have one person from the doc department who is appointed coordinator;
writers from each product/functional team work with their teams to compile
the release notes and then send them to the coordinator, who compiles the
overall document, makes it available for review, then incorporates
modifications. It's tedious and tense, since new issues are being sent in
right up until the last minute, but that's unavoidable, I guess. In our of
major sites (European) it's the teams' software-testing leads who review and
add release notes; in another (North American), it's dev leads and PMs. The
ST folks tend to stick to real bugs and to exercise judgment over which ones
are too insignificant to put in the release notes; dev folks want to put in
every bug including minor UI glitches and petty annoyances that may occur
under arcane circumstances; PMs also want to communicate about the product,
regardless of the fact that, for example, supported platforms and new
features are listed elsewhere, with a link from the release notes.

One unfortunate aspect of the way we do it, in my view, is that we include
the release notes in English and Japanese on the product CD as well as on
the web, with other languages available only on the web. The unfortunate
part is that we have to finish the English version several days prior to the
scheduled final build, in order to give time for it to be translated to
Japanese (the release notes are typically 3,000 or 4,000 words long). And
our localization department refuses to allow any difference between the two
versions on the grounds that it would be unfair to Japanese customers if the
English-speaking market had more up-to-date release notes than they do.

I'd be interested to hear how many of you have web-only release notes versus
release notes included in the installation CD(s), and how many with an
international client base translate the release notes for simultaneous
release.


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

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.