Re: Release notes and readme files

[Beth Agnew <beth -dot- agnew -at- senecac -dot- on -dot- ca>]

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: