Why are release notes important?

How to make release notes count

How to make release notes count
Image by : 

opensource.com

Congratulations! You're ready to ship the latest release of your software package. Now you need to make sure your release notes are in order. Sure, you could just slap "bug fixes and performance improvements" on the box and call it a day, but that doesn't really tell your users anything.

Release notes are for both support and marketing. They tell your current users why this new release is important to them and showcase your software to potential users. Thus, you want to make the content clear, understandable, and most importantly, relevant. There's no one way to write release notes, so this is general advice, not an edict.

One popular trend is to make the release notes a narrative that includes a lot of silliness. If that's your thing, go for it—just remember that jokes are often context-sensitive, and what you think is hilarious might be totally lost on your readers. And, of course, you can't forget to include the important information.

Getting started

Perhaps the single most important takeaway from this article is to write your release notes for the people who will read them. For user-facing software, focus on the user-facing behavior instead of the internal implementation. For example, say, "Clicking the 'Cancel' button will light your computer on fire," instead of "thermalEventTrigger defaulted to True in the cancelThatThing function."

Try to limit each note to a sentence or two. The point is to highlight the important part, not give a detailed explanation. If you have a public issue tracker, include a link (or at least an issue number) where readers can go find details if they're so inclined.

You don't have to lay out your release notes this way, but I like the following format. Start with the version number and release date. For major releases, you might also include a few sentences to highlight the major theme. For example, "This release focuses on adding an email client, because that's the eventual end state of all software."

Compatibility changes

If the new release introduces changes in compatibility or default behavior, highlight those explicitly. Your users will thank you, as will anyone who provides user support. Describe the cases where the behavior change will be encountered, how to address the change, and what happens if the user doesn't act on the change. For minor releases, you probably don't have any incompatible changes, so you can leave out this section.

Features and enhancements

Now is the time to brag about all of the cool, new stuff your software does, but remember to focus on the user's perspective. For example, "The software now supports the automatic detection of pictures of lunch and posts them to Instagram."

Issues resolved

No software is perfect, and this is the section where you tell readers about all of the hard work your team did to make the project a little better. Write these notes in the past tense, because the bad behavior is dead and gone. If it's clear where the bug was introduced, include that information. Some projects include bugs in the documentation in this section as well.

Known issues

Because no software is perfect, there are always bugs left unsquashed. This section is the place to list those. You don't have to confess everything; focus on the bugs that impact functionality, especially if they were discovered since the last release. Write these in the future tense, and when you've addressed it, you just have to change the verb tense and it's ready to move up a section.

6 Comments

kikofernandez

Could you give a few examples of Open Source projects doing this right?
Thanks

Vote up!
0
Vote down!
0
bcotton

Great question. I don't have any good or bad examples at the ready, though I should have. I'm biased due to my use of and contributions to the Fedora Release Notes, but I generally like how they turn out: https://docs.fedoraproject.org/en-US/Fedora/25/html/Release_Notes/index....

That's not necessarily a great example because a distro is a much different beast than a smaller software package.

Vote up!
1
Vote down!
0
gamesbook

Django is quite good; because its aimed at developers, the sections include:

* What’s new
* Backwards incompatible changes
* Features deprecated
* Features removed

See: https://docs.djangoproject.com/en/1.10/releases/1.10/

Vote up!
2
Vote down!
0
bcotton

Wow, those are really good. One other thing I like about them is that the features are grouped, which makes it easier to skim and find what you're looking for.

Vote up!
0
Vote down!
0
Lenz Grimmer

We just recently restructured our blog in a similar fashion, based on the recommendations from the "Keep a changelog" project: https://blog.openattic.org/posts/introducing-a-new-changelog-format/

Vote up!
1
Vote down!
0
bcotton

Thanks for your comment. I hope your users like the new format.

Vote up!
0
Vote down!
0

Comment now