Amazon.co.uk Widgets





A Great Way to Write Release Notes

Category : Documentation, Technical ยท by

The Trouble With Release Notes

This week I have been shepherding our latest release into the production environment and I got stuck with the task of doing the release notes as well. The trouble with release notes is that they are boring and unloved.

The Problem

Release notes tend to be just lists of changes which hardly makes for inspiring reading. If you’re bored when writing them then why would you expect anyone reading them to continue to plough through the dross. You won’t necessarily have a large audience and you don’t need to write the next best seller but you can make them more engaging and easier to digest for those that do read them.

What Makes for Good Release Notes?

Wikipedia defines release notes as “…documents that are shared with end users, customers and clients of an organization…[that] detail the corrections, changes or enhancements made to the service or product the company provides”. This means that you have an audience of internal and external users that want to know what has changed in your product since the last release and so you should help them do this as quickly and pain free as possible.

In order to digest release notes it makes sense to order them into sections which means you have to do the work of sifting through the changes to categorise them for your readers. I finally settled on a template with help from this post.

Release Notes Template

  1. Release Title and Date

    This should contain the name of the product, the version and the date of release.

  2. Summary

    This should be a headline description of what’s in the release. A few sentences should do.

  3. New

    List any new features and functionality here. This might be at the user story level and could include links to the work item.

  4. Improvements

    Outline what changes and enhancements you have made to existing features. Again, include a link to the work item if you can.

  5. Fixes

    Put your bug fixes so that your users know that you are removing errors from the system.

  6. Operational Changes

    These are under the hood changes that are not necessarily important to the users of the system but should be tracked. Include items here such as infrastructure changes or changes to deployment.

Example

Release: MyApplication version 3.2.0 [Release Date: 1 Jan 1970]

Summary
This release introduces the ability to delete bits and bobs from the settings screen and enhances the reporting screen by adding a back button. The save to disk bugs have been fixed and the server hostnames have been tokenised as part of the deployment process.

New
Item 48923 Delete bits from settings screen
Item 48924 Delete bobs from settings screen

Improvements
Item 51344 Provide a way back from reporting screen
Item 48555 Restyle reporting tables to fit on mobile devices

Fixes
Item 48871 Error when save to file when filename longer than 12 chars
Item 48872 Error when save to file when filename has underscores

Operational
Item 48801 Tokenise server hostnames during deployment

Add Humour

I’ve also had some success with a slightly more humorous version, but you might have to think carefully about your audience.

Release: MyApplication version 3.2.0 [Release Date: 1 Jan 1970]

The One Where (Summary)

Awesomeness (New)

Twerks (Improvements)

How Did We Miss These (Bug Fixes)

You Don’t Need To Know (Operational)

Love Your Release Notes

Ultimately, making your release notes clear and unambiguous shows that you are committed to engaging with your end users and can only help with the success of your product. Do your readers a favour and love your release notes.

SHARE :

Leave a Reply

Your email address will not be published. Required fields are marked *