RE: Address this. . .

Subject: RE: Address this. . .
From: "McLauchlan, Kevin" <Kevin -dot- McLauchlan -at- safenet-inc -dot- com>
To: Gene Kim-Eng <techwr -at- genek -dot- com>, "techwr-l -at- lists -dot- techwr-l -dot- com" <techwr-l -at- lists -dot- techwr-l -dot- com>
Date: Fri, 12 Mar 2010 13:45:56 -0500

This is one of those "we've always done it this way" things.

In our case, our Release Notes have always stated
- what is supported (hardware, software, firmware
versions for components); in other words, what
constitutes this release,
- what operating systems/versions are supported to
run the software client portions,
- what the new features are,
- any notes about incompatibility, special
circumstances, cautions,
- stuff that didn't make it into the main docs but
might be important to know,
- what issues/bugs have been fixed, and
- what outstanding issues could not be fixed at this time.

Separately, we do have a trouble-ticket system for
customers, and they can indeed look up the status
of their own issues - not sure what access they
have to other customers' issues. There are privacy
concerns - we can't be a source of competitive
"business intelligence" among our competing customers.

But while those customer-generated issues are brought
into the working database (MKS) that developers and
testers use, there are also lots more bugs that need
to be tracked, including:

- some discovered by our field engineers
- some discovered by our developers while working
on something else
- some discovered by our testers when they modify
or add to test cases
- some discovered by our testers while they are
in pre-release testing of newly-developed h/w,
s/w, and f/w.... not to mention builds issues
- marketing/product-manglement-inspired features
- etc.

Many of those never see the light of day outside
the company, while others - that no customer
specifically asked about - are made public because
they could affect customers and we want them to
hold off, or employ workarounds until we can kill
a bug.

Anyway, I know that some will say that any "what's new"
stuff should go in the main docs - for me that's
mostly all WebHelp - but I don't use such docs for
announcements. I just write 'em matter-of-factly
as "this is the way it is as you find it". Yes, I
do wave a flag if there's a change between versions
that would have a significant effect on existing
customers/users, but that's on a per-activity basis.
"The xyz feature might affect your existing scripts..."
"ABC algorithms no longer default to xxx key-size,
for security reasons." Or, similarly, "The evolving
FIPS 140-2 standard now prohibits such'n'such algorithms
or key sizes, therefore the system makes them unavailable
if it is operating in 'FIPS-mode'." "Versions of JJJ
older than x are no longer supported."

- K

> -----Original Message-----
> From:
> techwr-l-bounces+kevin -dot- mclauchlan=safenet-inc -dot- com -at- lists -dot- techwr [mailto:techwr-l-bounces+kevin.mclauchlan=safenet-> inc -dot- com -at- lists -dot- techwr-l -dot- com] On Behalf Of Gene Kim-Eng
> Sent: Friday, March 12, 2010 12:06 PM
> To: techwr-l -at- lists -dot- techwr-l -dot- com
> Subject: Re: Address this. . .
> I'll second this. Don't mention the unresolved issues in the
> release notes if
> you can avoid them; concentrate on the resolved ones. If
> policy dictates that
> they must be listed, describe them as known but unresolved.
> You will already be
> annoying the person who originally reported the issue enough
> by saying it hasn't
> been resolved without rubbing salt in the wound by saying you
> haven't even
> bothered to look into it.
> Gene Kim-Eng
> ----- Original Message -----
> From: "Bill Swallow" <techcommdood -at- gmail -dot- com>
> .> Ah, interpretation... I'm not going to answer your
> question. Instead
> > I'll just offer advice:
> >
> > Don't include unresolved bugs in the release notes.
> >
> > does your company have an online bug base? Do customers have the
> > ability to log in and see the status of their reported bugs? If not,
> > look into it. If so, your work is done (with regard to unresolved
> > bugs).
> >
> > IMHO, release notes should focus on what IS in the release
> and not on
> > what isn't.
> >
> > I'd personally not like to look at the ingredients list on a box of
> > Froot Loops to see "Non-Ingredients: real fruit, ground beef, lamb's
> > tongue, lard, wood chips, roofing tar..."
>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.


Use Doc-To-Help's XML-based editor, Microsoft Word, or HTML and
produce desktop, Web, or print deliverables. Just write (or import)
and Doc-To-Help does the rest. Free trial:

Explore CAREER options and paths related to Technical Writing,
learn to create SOFTWARE REQUIREMENTS documents, and
get tips on FUNCTIONAL SPECIFICATION best practices. Free at:

You are currently subscribed to TECHWR-L as archive -at- web -dot- techwr-l -dot- com -dot-

To unsubscribe send a blank email to
techwr-l-unsubscribe -at- lists -dot- techwr-l -dot- com
or visit

To subscribe, send a blank email to techwr-l-join -at- lists -dot- techwr-l -dot- com

Send administrative questions to admin -at- techwr-l -dot- com -dot- Visit for more resources and info.

Please move off-topic discussions to the Chat list, at:


Address this. . .: From: McLauchlan, Kevin
Re: Address this. . .: From: Bill Swallow
Re: Address this. . .: From: Gene Kim-Eng

Previous by Author: Address this. . .
Next by Author: RE: Address this. . .
Previous by Thread: Re: Address this. . .
Next by Thread: Re: Address this. . .

What this post helpful? Share it with friends and colleagues:

Sponsored Ads