RE: Address this. . .

["McLauchlan, Kevin" <Kevin -dot- McLauchlan -at- safenet-inc -dot- com>]

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
-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- 

To unsubscribe send a blank email to 
techwr-l-unsubscribe -at- lists -dot- techwr-l -dot- com
or visit http://lists.techwr-l.com/mailman/options/techwr-l/archive%40web.techwr-l.com


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
http://www.techwr-l.com/ for more resources and info. 

Please move off-topic discussions to the Chat list, at:
http://lists.techwr-l.com/mailman/listinfo/techwr-l-chat