As soon as I thought about writing a post about Release Notes, I got that old Englebert Humperdink song stuck in my head, “Please release me, let me go..” and it’s been stuck in there ever since. When that played on the radio when I was a kid, it was the worst earworm ever! But it has nothing to do with writing a good set of release notes, and it just serves to distract me from the task at hand.

As technical writers, we are tasked with documenting (we hope) multiple releases of successful software products. A vital part of that job is letting customers know what has changed from one release to another, especially when something might alter the way a customer uses the product. Sometimes the change is exciting – like a new feature. Sometimes it’s less glamorous, like the deprecation of code functions.

At their most minimal, release notes are merely called changelogs, and are not full-blown release notes at all. Changelogs are just companions to the documentation that can be sent along periodically and take far less work than the notes that accompany a Generally-Available Release. For a major GA release, you can and should anticipate preparing not just technical notes, but a greater suite of materials that will help your product succeed in the market.

Ahh..but I am just a lowly tech writer, you say. Well, if you choose to remain so, then only prep a section of tech doc that discusses the technical aspects of the release, and there you have it. If you want to view your software as an asset and you’d like to continue writing doc for it and for your company, listen well.

What to Include in Release Notes:

New Features and Functions

Let readers know what new features are packed in to the product, and how those enhance their experiences. The Release Notes section allows for a teensy bit of latitude where you can provide an information-loaded summary of what that feature means and how users can implement it. What does it mean to them? What is the business value? Depending on your business’ practice, you might be able to include a screenshot, an illustration, or a video demo.

If the feature or function came out of ideation, you could link to the community where the request was made, so that customers know that their voices are being heard. They really dig that.

Make sure that New features is the first item in your Release Notes. Don’t let it be overshadowed by anything else, like…

Bug Fixes                                                                                         

Listing the bugs that your team has encountered and corrected is important in the upfront Release Notes, but even more important is linking to the documentation where the bug reports and further information resides. It’s no good to just say, “hey we fixed this,” but not to say “here’s where to get that new stuff.” I’ve seen plenty of doc that does the former but not the latter. It’s just a courtesy to point your users directly to the goods.

It is important to note the Bug Fixes, but don’t let them get anyone down. They were glitches, after all, so celebrate the fact that they were Fixed! Go, you! Because next up, you deed to call attention to deprecations.

Deprecations                                                                    

Nobody celebrates these, and yet you have to let users know about the parts and pieces that are just no longer useful. If part of your product is headed out to pasture, you’ve got to say, “sorry, folks, this is being taken off the shelf.” You don’t necessarily have to say why, because hopefully you’ve covered that in sprint reviews and whatnot, but you do have to make sure you place this prominently in your Release Notes, because not everyone attends those review meetings, or knows in advance about such retirements.

On the other hand, don’t dwell. Do let customers know if there is an alternative – like substituting margarine for butter or stevia for sugar, that sort of thing. Absolutely link to a migration guide so that they know how to get the job done moving from one release to another. Don’t leave anyone hanging without the tools they need.

Why did I bother to put this little guide together?

Well, because I have seen some good release notes and I have seen some bad release notes. I troll around in other product documentation; I don’t keep my head in the box at my own company. I find it intriguing to look around at best practices and see what’s going on. I strategize and learn. One of the things I like to do is to put myself in the shoes of my user. If you don’t do that, you are not a good writer. There. I said it. We are not writing fiction here, folks. These are user guides. USER.  So look at things from that vantage point and see if it works. Not only if it works, but if it is easy. Do you enjoy it? I don’t mean if it’s superfun, because no, it is not super fun. Dancing on Saturday night with your besties is super fun, but is it a pleasant experience that you do not hate at 2:00 on a Thursday? Good. Then you wrote some good documentation and that is all we can ask for. Congratulations.

Once you have that all set and in place, jot down a section of “Other Notes.” This is stuff you grab from UX, from your internal SMEs, things that are overlooked and the orphans of the whole set. The “junk drawer,” if you will. Toss it in a section, build something for it. There is a reason that nearly all of us have a junk drawer in our kitchens – we have odds and ends, but they are useful little nuggets. Your Release Notes might have those, too. But before you toss in too much stuff, take a good look at those nuggets and really ask if they don’t belong in one of those other categories. They truly might. A very smart designer friend of mine once told me that stacks of things are really just unmade decisions. She’s right. So don’t stack your stuff, that junk drawer of doc, just because you don’t want to deal with it. Make some decisions. But even that smart designer friend has a junk drawer. It’s just a nearly-empty junk drawer.

And there you have it. Delight your customers with neat, tidy, efficient user-friendly Release Notes, and be on your merry way. Strategy 101.

By the way, I think the real reason I wrote this is because…guess what…I just finished writing, you guessed it…a whole new set of release notes. With a very small junk drawer. Yay, me.