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.

• Additions
• Removals
• Changes
• Fixes

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.

BareBones Software inserting a little attitude into their 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://bbedit.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.

MS .Net Installation - You can now disconnect from the Internet.

I almost blew it too by clicking the “Cancel” button because (1) I thought it was all done and it was the only button shaped thing available, (2) I do not want to disconnect anyway.

Luckily, I noticed in time that the progress bar was still working.

I know Microsoft takes a lot of abuse for no reason other than that they are M$, but it’s just so easy with stuff like this.

Okay, so…when I first glanced at this text, I did a triple-take because I thought it read, “The best way to stay updated with the Design Encyclopedia is through our ass…

It’s actually “RSS,” not some kinky techie-mojo. Just thought I’d share.

(It’s from The Design Encyclopedia, which is actually a cool project.)

As I logged in to a local coffee shop wireless network, I got this message. I took a snapshot because I thought the error text was telling. Clearly, a programmer wrote it.

Else you can always goto following url to logout…

Here’s the thing: nobody actually says else and goto isn’t actually a word. And, instead of url, why not just say, Or, you can logout at http://1.1.1.1/logout.html.

I like the peronality coming through what would normally be very dull error text.

I guess they are trying to write to their audience’s level.

I happen to have the “Microsoft Manual of Style for Technical Publications, Third Edition” on my desk, and I found no entry for anything resembling “open source” in it.

Somehow, I wasn’t surprised.

Searched Google for “e-mail” and returned 1,300,000,000 results. But, also got Google’s “Did you mean: email?” prompt, which suggests that Google, at least, has “email” as a preferred term with “e-mail” as a variant term.

I almost always write “email,” but when I think about it, putting in the hyphen makes sense to me. But then, our language is changing, and probably the version without the hyphen is already accepted as proper English.

I’m making progress, but too slowly. So, Chey told me to turn on some techno music and write to this blog for 5 minutes. So, I am.

Any other bloggers out there getting comments that are suspciciously similar to spam? Like a comment that has little do to with the post, and has a link to a web site about some kind of HGH drug or worse?

I just deleted about three of them from this site. How irritating. I wonder if someone has written a script that is allowing spammers to use these blogs to direct links to their sites. Or, if someone is actually doing it by hand.

• Snowfall, Snowdevil, etc. published in the Norther Michigan Journal sometime in 2000.
• I am unable to wrap my arms around a tree and then jerk it from the ground published in Cross Connect, Issue 14, Nov 1999.