Working on documentation at OpenLogic, I spend a lot time looking at release notes. When a new version of a project we support is released, I need to find out what will be most important and useful for our customers to know about it. Whether I'm trying to find the latest security patch or just looking for the highlights of the new version, some release notes are much easier to view and work with than others. 

Finding the Release Notes

Sometimes, I start noticing that the release notes are poorly presented before I ever find them… because I can't find them. I'm not sure I've ever seen a project that didn't have release notes at all, but some projects organize their information in such a way as to require an Easter-egg style search. This includes projects that only include the release notes with the project download. 

Including release notes with the download is a very good thing. It ensures that your users always have access to them, no matter how they obtained the project. However, it's unfriendly to make users dig. Important project documentation is best included in either the top level of the project, or in a top level 'Documents' folder. (This is also true for licenses, but that's another subject entirely.). More importantly, it's a hassle to compare multiple versions of the project when you have to download each version and open its release note file to get at the information. For this reason, a project that wants to make its release notes easily accessible should also make the notes available online.

Many projects have a release notes file that is linked in the same location, but separate from, the actual project download. This is the default system for projects on Sourceforge, for instance. On that site, there's a project download link, and right next to it is a convenient clipboard icon to access the release notes. While this variant makes it convenient to find the release notes, it's a poor format for comparing them across several versions. If you are are currently using, say, 3.0, and want to know how upgrading to 3.9 will affect you, you probably want the notes for 3.1, 3.2, 3.3.and so on – not available in this scenario.

Some projects have one central 'Release Notes' document that shows the changes across all of the tracked versions. This simplifies viewing changes over multiple versions and comparing different versions. About the only downside is that projects sometimes neglect to make this log easy to find. While notes linked to versions are usually located right next to the download, single document release notes tend to get hidden in their own little corner of the Web site without a good way to locate them. 

Another option is a Jira repository. This lets your users decide for themselves what changes to view. This is highly flexible, but can be overly complicated. If you want your Jira-based release notes to be accessible, be sure to make it simple and obvious how to search by version.

Using the Notes 

Assuming your users find your release notes, they need to be able to view them and make sense out of them. The actual format might vary from plain text files to bug-tracking software, but I find that matters less than how the information is presented within the format. There are several presentation techniques that improve usability.

Organize the information: Organizing release notes either by priority or category (feature, bug fix or enhancement, for instance) enhances the overall readability of the notes. A list of new release information organized by bug number is likely to appear arbitrary and unhelpful to an outside user. 

Consistency: Being open source, projects often have bugs and features submitted by developers with very different ideas of how to describe their work. When you look in the bug fix section and see:

• Repaired bug in modelview.create().
• Problem in modelreport