Release notes, what for?

Question

What are release notes for and who reads them? Should/could they be automated by just spitting out bugfixes for the current release, or do they warrant careful human editing? So, anybody with a link to best practices(reasoning behind) in regards to software release notes?

Answer 1

This really depends on who your application is built for and your organizations goals. However, I tend to believe that release notes need to be a concise listing of important key additions, enhancements, or fixes that are included in the particular release.

Sometimes a simple dump of the bug tracking system information is enough, other times, I find that they need to be refined.

The key is that typically Release Notes are believed to be the "Hey look at what we did" type listing of changes.

Answer 2

Bugfixes and added features. Users will read them to determine if they should go to the trouble of installing an incremental upgrade, or wait until the next release because this one doesn't add any features they need or fix any bugs in features that they were using.

I'd say they at least require a human to read through them and make sure that each note is useful. It depends how good the comments on your bug fixes are.

Answer 3

Our release notes are human created instead of machine created. The cover three main topics.

1. What is included in the releases (list of files)

2. How to install it

3. What changed since the last version (especially if the changes are not in the manual yet).

items 1 and 2 don't chnage much from version to version, but they need to be reviewed. Item 3 takes the most work.

Answer 4

Release notes and READMEs can be really important if your customer has to take special action in addition to normal procedures in order to upgrade. It also be useful to warn customers/users of any db upgrades that can automatically happen as a result of installing a newer patch. The way I see it, Release Notes and READMEs should be written for the System Administrator audience. So include the kinds of things they would want to know about: summaries of important changes, how to install, known bugs, anything your software might do that would make someone pull their hair out, etc.

Answer 5

I habitually read release notes. I tend to want a full comprehensive list of feature changes ( or as good as plausible ) in order to greater empower my utilization of the new product.

I want to see when certain critical bugs, or critical security issues are solved.

Answer 6

Release notes are also very important in production environment.

They help answering the age-old question:

What the heck is currently running into production ?

Or the more refined question: does this bug has actually been fixed in this release ?

Answer 7

Release notes are also important to your testing organization (if you have one), so that they know what's changed in the release and needs testing.

Answer 8

Release note depend of your organization.

I can talk for my organization. We use release note in PDF format and every time we publish a clickonce or a backend version. We send to office manager the Release note. This is a document used by the top administrator of the business (not only IT). This document is a way for them to know what is going on. What have changed, new features that are now in production, bugs fixed, and other thing that they might want to explain to their user.

This is a document that can be between 3 to 4 pages, describing the job that has been done in this version with brief words.

Answer 9

This is of course highly dependent on the type of application/service/whatnot,
but I've found that reading the release notes of my favorite developing tools etc..
often make me stumble upon nice, interesting or even killer features that I'd probably miss if I did'nt at least skim the notes.....well, perhaps not killer, but you get my drift ;-)

As most computer power users(now what kind of expression is that...)
I never bother much with ordinary documentation, so this gives me
that little something extra something besides clicking, hovering and faq'ing...

Answer 10

Release notes are for testers and users to know what's new/changed. Additionally, release notes can be used as supporting documentation when billing a new "version" of a software for client that you are building for them. v1.31 seems a lot easier to relate and drill into.

Rather than compile both lists manually, if you can use your release notes to do that for you it's great.