I confess, I’m a release notes reader, and I’ve read some overwrought release notes lately. When you use them like an installation guide, a features list, or a list of software conflicts, you’ve got it wrong.
The purpose of release notes is simple:
Release notes explain what changed with this version of your software. Period.
I hope this article will help you write release notes with clarity and brevity.
Title format for release notes
The title for your document should include specific information:
- Name of product
- Version number
For example, if your product is RubberDucky and this release is version 3.3.5, the title for your release notes document should be RubberDucky 3.3.5 Release Notes.
Make the title big and bold at the top of the page. Refer to it in links exactly as the title reads.
Consider following the title with these bits of information.
- One sentence overview of the product
- Date of the release
- System requirements
- Note changes, like “Discontinued support for Windows XP.”
- Link to installation instructions
- Link to a user manual
- Link to a release notes archive
Other sections in release notes
Break the release notes document up into sections, each with its own heading. Here are some sections to consider.
Keep the actual descriptions brief. Release notes are often little more than a bullet list of updates, and that’s fine. If there are a series of small technical changes, try to describe them as a theme. For instance, “Improvements to the communication between the software and our servers.”
However, if there is an update that is important for users to understand, do not sacrifice clarity for brevity. Write enough of a description to explain the feature, but no more than necessary.
How do you know if an explanation is too short or hard to understand? Ask someone who is familiar with the software but doesn’t really know about the release to read the explanation and explain it to you in his or her own words.
What about personality?
Release notes should be easily scannable, and inserting witticisms should be avoided. However, if the company is proud of some feature, it doesn’t hurt to brag about it, so long as it is brief.
Here’s a nice example from TextWrangler 3.0 Release Notes.
What about posting existing, known defects?
This question quickly becomes a philosophical one. In my opinion, a company should be transparent about known defects with their software and earnestly try to fix those problems. You can see this type of behavior with some open source projects in that they have a public defect tracking system. The bugs are out there for the world to see. With enough of a user-base, defects with your software will probably become known eventually anyway.
However, I do understand that in some cases advertising known-defects is a security and stability liability and just shouldn’t be done. My preference is that that sort of decision is made on a defect-by-defect basis, and not as a corporate blanket statement.
Regardless, known defects or incompatibilities do not belong in your release notes document. You could, however, link to a list of them in your release notes.
Organizing archival release notes
What do you do with all those release notes from prior versions of your software? Archive them on your website so you and your customers can get to them.
One page, all release notes
If your release notes are brief, you might want to include each version on a single page. The most recent release notes should be at the top of the page. Fetch Softworks currently takes this single page for all notes approach.
One page of release notes per version
For the sake of clarity, I would prefer to have release notes for a specific version on that single page, with a release notes archive page that links to every version. BareBones Software takes this index of release notes approach.
Some companies keep a current release notes page up-to-date so they don’t have to continue updating links. Again, BareBones follows this approach: http://barebones.com/support/bbedit/current_notes.html
Do you have good (or bad) examples of release notes?
Not having seen any “best practice” document for release notes, I wrote this article. Do you agree? Disagree?
If you have examples of great, or really awful, release notes, please comment with the web addresses so we can all see them. Thanks.