Release notes and readme files

[Beth Agnew]

I'm very much against providing a lengthy list of bug fixes to users. I 
think it really affects credibility of the product. A new purchaser of 
the system is not going to want to know that 40 bugs have been fixed. 
Deep down, sure, they want to know that you are always making the 
product better, but being reminded that there have been so many fixes to 
the latest version begs the question, How many bugs /didn't/ you find 
and fix yet? I think it's poor customer service. However, there are 
technical people who may want to know that certain bugs have been dealt 
with. This can be done very easily via a blind webpage for which you 
provide the link in the readme file or release notes. Then only those 
who have the need to know will bother looking it up.

Some organizations track user bugs by giving the user a bug number to 
refer to. The users affected would want to know that their bug has been 
addressed. This should more properly be done in individual communication 
or by referral to a webpage as mentioned above, not by including it in a 
long list. I have used this approach with customized software. End users 
don't normally read readme files, so if you really want to include the 
bugs fixed list, that would be the place for it.

Release notes should be written to inform the user of improvements and 
enhancements. I prefer to call bug fixes "improvements" when I'm writing 
release notes or talking to users. They might have recognized a 
particular problem, and be very glad that we've addressed it, but being 
reminded that it's a "bug" is not the best approach from a marketing 
standpoint. Don't forget that we do have a role in helping our companies 
be successful in the marketplace, so we should be mindful of how we are 
presenting things to the users and buyers of our products.

I have an example release notes document if anyone wants it, just e-mail 
me offlist.
--Beth

egalite wrote:
> Hello fellow techwhirlians...
>
> I've tried googling, and have read the 4 pages in the Microsoft style guide,
> but information appears to be sparse. 
> Is anyone aware of a best practice guide on how to write release notes or
> readme files? What's the real difference between them anyway? The MS example
> kind of lost me.  
>
> My PM wants to produce release notes that basically contains a list of all
> bug fixes. I'm not sure how useful this would be to an end-user, especially
> if the product's not an off-the-shelf one (although it might be in future). 
>
> Also, any thoughts on providing the readme in a format other than text?
> We're considering supplying it in PDF.
>
> Thanks,
> Trish :)
>
> ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
>
> WebWorks ePublisher Pro for Word features support for every major Help 
> format plus PDF, HTML and more. Flexible, precise, and efficient content 
> delivery. Try it today! http://www.webworks.com/techwr-l
>
> Easily create HTML or Microsoft Word content and convert to any popular Help file format or printed documentation. Learn more at http://www.DocToHelp.com/TechwrlList
>
> ---
> You are currently subscribed to TECHWR-L as beth.agnew at senecac.on.ca.
>
> To unsubscribe send a blank email to 
> techwr-l-unsubscribe at lists.techwr-l.com
> or visit http://lists.techwr-l.com/mailman/options/techwr-l/beth.agnew%40senecac.on.ca
>
>
> To subscribe, send a blank email to techwr-l-join at lists.techwr-l.com
>
> Send administrative questions to lisa at techwr-l.com. Visit
> http://www.techwr-l.com/techwhirl/ for more resources and info.
>
>   

-- 
Beth Agnew
Catch the Buzz: http://bethbuzz.blogspot.com
STC Presentation archived at:
http://www.301url.com/podcasting

Professor, Technical Communication
Seneca College of Applied Arts & Technology
Toronto, ON 416.491.5050 x3133
http://www.tinyurl.com/83u5u