TechWhirl (TECHWR-L) is a resource for technical writing and technical communications professionals of all experience levels and in all industries to share their experiences and acquire information.
For two decades, technical communicators have turned to TechWhirl to ask and answer questions about the always-changing world of technical communications, such as tools, skills, career paths, methodologies, and emerging industries. The TechWhirl Archives and magazine, created for, by and about technical writers, offer a wealth of knowledge to everyone with an interest in any aspect of technical communications.
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
- 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
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
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."
> -----Original Message-----
> techwr-l-bounces+kevin -dot- mclauchlan=safenet-inc -dot- com -at- lists -dot- techwr
-l.com [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: http://www.doctohelp.com
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: http://www.ModernAnalyst.com
You are currently subscribed to TECHWR-L as archive -at- web -dot- techwr-l -dot- com -dot-