Everyone has their own opinions on what release notes need to be, or how in depth they should be. Some even go so far as to make them epic stories, like the now legendary release notes for Tumblr’s iOS 4.3.1 release. Regardless of your take, there’s a few simple guidelines to make things useful without giving away so much information that a competitor can pick up on all the new nuances of your product.
Make it Human Readable
This may sound obvious, but you have no idea how many times I’ve come across release notes which are just jumbled together from the commit history. Take the time to actually organize it. You don’t have to do much formatting to it; even just bullet points are fine.
If you want to break things down to make it even more human readable, consider breaking the items down in to the follow categories so that users can immediately jump to what they’re interested in:
| Section | Description |
|---|---|
| Added | All your new features |
| Changed | Anything that has changed in current functionality |
| Deprecated | Notify your users of features which will be removed soon; include dates if possible |
| Removed | Features which are now completely removed |
| Fixed | Bug fixes go here |
| Security | To be used with any vulnerabilities you’ve corrected and items you’ve preemptively strengthened the security |
Don’t Just Dump Your Commit History
It honestly pains me to see things like “merged master in to working dev branch to fix a bug” or even just “Committed eb49c74e[…]778e”
This is nothing but tech noise. What was the bug? Did it affect the end user or just help improve performance on the back end? Just what exactly is Commit “eb49…” anyway?
Dumping your commit history also runs the risk of your customers wondering how stable your code is. If you’re like me, you’ll commit your code often, especially on larger pieces of work. It makes sense to the engineering world. It doesn’t make sense to the rest of the world though, and could cause customers to wonder how stable things are if you’re constantly changing code.
But Don’t Leave Things Out
I heard a complaint from a colleague of mine a few months back that they were happy that the team they were working with was finally starting to put out decent release notes. This was immediately followed by a large BUT… (Oh my God, Becky!) You see, while they were finally putting out release notes, they were leaving out large portions of interface and functionality change. My colleague ended up losing over a day of productivity due to having to contact the team over what had really changed and then waiting for a response (we won’t talk about having to wait longer for clarification to the response…).
There’s nothing worse that reading through the notes and then going to the site to find that the entire process you used for something had changed, and there was no mention of it.
Customer Specific
In one job I was in we had not only a large number of customers, but several very large customers we would also do custom integrations and specialty work for. As the business was a SaaS model, all our customers were competitors to each other.
Imagine the joy Company X would have with finding in the release notes something to the effect of “Created new API integration to support Super Widget Customization Sales for Company Y.” When it comes to Competitive Intelligence on your competitors it doesn’t get much better than that.
We ended up having multiple release notes for each release. One set of notes was all the generic items which would impact all customers. This was what was posted to the general public. Custom release notes were then created and sent to the contacts for each of the customers where specific custom work was released. If no custom work was released we sent a copy of the generic release notes to the key customers as part of a bigger initiative to keep them informed of what was happening.
Have Some Fun With It
Now that you’ve improved your release notes, it’s time to have a little fun with them. You certainly don’t have to, and some organizations may even frown upon it, but if you can, add a little levity to things. Having a bug fix note of “Corrected issue preventing users from uploading a new profile photo” isn’t nearly as engaging as “We know you’ve been trying to show off your new hairstyle/beard/glasses/etc to everyone, so we’ve fixed the bug that caused an error when you tried to upload a new profile photo. Sorry about that, it seems our developers don’t change appearance as often as our customers do!”
As an engineer or a manager, you should be able to help with writing the release notes. Yes, many Agile processes say this is the responsibility of the Product Owner, but that doesn’t mean you shouldn’t offer to assist and make their life a little easier. Adding in specifics from engineering can often help the end user, especially when it’s a technical update such as a new API. After all, isn’t that what teamwork is about?