Muggles Don’t Understand Your Release Notes

Hey software friends, we need to talk.  In 2016, 61% of Americans are carrying smart phones and that means they’ve also got an app store on a device in their pocket.  My iPhone reports to me when I have updates to applications that need to be installed.  Many times, I see a screen that looks like this on my phone:

Release Notes Gone Bad

Release Notes Gone Bad

I’ve hidden the application names and icons in an effort to protect the innocent.  The problem with this approach is easy to identify when your non-technical friends and family members ask about the update notifications like this on their phones or tablets.  The conversation sounds something like:

“What are these updates my phone wants me to install?”

“There are some bug fixes for the applications you have installed that the author of those apps wants you to install”

“Will it fix that issue that I’m having and I’ve been calling you about?”

“I don’t know, the update just indicates, ‘various improvements and bug fixes'”

“Then I’m not installing it, it will probably just make my problem worse”

This is not a drill… Everyone is reading your release notes!

Seriously tech friends – when you publish software updates, people want to know what you are changing.  Other tech workers may stomach a “fixes and updates” release note every now and again, but in a world where the non-technical are seeing your notes, this is an opportunity for customer service engagement and you’re doing a TERRIBLE JOB at it.

When I used to publish release notes for NuGet, an open source project, I would give a one or two sentence description of the issue addressed and a link to the original issue on GitHub that discusses the reported issue and links to the software that fixed it.

Some of my NuGet Release Notes

Some of my NuGet Release Notes

Do you need to be this in-depth?  No… but give us a reason to install your update.  If you don’t have space in the minimal field size allocated on your app store or package management service, provide a link for more details.  You can list more in a blog post, a release notes part of your docs, and even include images to show off your cool updates.

Please software authors – start telling us a little more about what work you’ve accomplished in each release.  Its the right thing for your customers to show them that you are fixing things that they care about and gives credit to your development team for their accomplishments.

  • GeekyMonkey

    These say nothing release notes are unfortunately the norm. Even from the big dogs. I have seen some exceptions where the notes are both informative and light hearted. It’s a good way to remind your users that there are actual humans behind these apps, and make them feel more connected with you.

    Good examples here: http://releasenotesheroes.tumblr.com/

  • jbrinkman

    I think the problem is that often it is hard to say what is fixed without diving into a lot of technical details which will sail over most peoples heads. When you try to summarize it, you often end up with meaningless statements which really don’t tell a user that the bug they are interested in is fixed. I agree that a generic “fixed bugs” type statement is not enough, but I have had plenty of releases where the actual items fixed just don’t make sense to anyone who is not a programmer.

    • I disagree. You can certainly have shorter descriptions of changes like:
      Improved performance on check-out screen
      Fixed validation while adding a negative number of items to the cart

      For more technical products, I would expect more technical descriptions in the release notes.