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:

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.

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. It's 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.