As a Designer I want better Release Notes
Simple visual design, applied to plain text release notes
Writing release notes is a contentious issue. There are some companies who simply don’t bother (often with good reason) and some companies who put their heart and soul into creating something truly engaging.
By applying a simple structure and some basic formatting, you can dramatically improve the appearance, readability and experience of your release notes using nothing more than the plain text characters at your disposal.
This article covers a few key areas, finally defining “the perfectly formatted release note,” which you can jump to – right at the end.
Best Practices
Summarise first. Tell Later.
Your bestest friend… TL;DR (too long; didn’t read)
Start with a summary, for the people with no time. But then go into the details and please the update nerds.
Remember the major release
Need to release a quick fix after a major release? Make sure to paste the major release notes below, reminding everyone of the great work you’ve done.
Make it easy for people to get in touch
Have a consistent sign off section that highlights feedback avenues could help avoid negative reviews.
Keep it short and to the point. “We value your feedback, get in touch here [email]”. As a UX professional this one is key. The easier for your users to speak with you the better.
Basic Formatting
Bullets
- Break it down, we don’t want paragraphs. We want summaries.
- If in doubt, start each point on a new line beginning with ‘•’
- Get creative with your bullets for extra impact. ESPN use [+]
- They’ve even gone an extra mile, also creating a sub bullet —
- Getting creative is fun. However, don’t add gimmicks for the sake of gimmicks. If you do something once, make sure you do it every time, keeping a consistent style. ESPN do a great job of always sticking with their custom bullets.
Titles
You need to section your notes with suitable titles that stand out. CAPITAL LETTERS are your titles best friend. So are — * = ~ # + … to wrap either side of your title. Whatever you need to get the job done. Just make sure you’re consistent, always use the same style for all headers.
Sections
NEW FEATURES ✨ ~vs~ IMPROVEMENTS 🤕 ~vs~ BUG FIXES 🐜
Take your titles further. Break down your release into new stuff you want to shout about and things you have fixed you want people to know about.
It goes without saying, the new stuff should always come first.
Space
Let it breathe. Make it easier for users to see the main points and not a wall of text.
Writing Styles & Content Ideas
Don’t be afraid to call out the bug 🐜 …🐛🐝🐞🕷
Fixed a bug that affected a lot of people? Tell them about it! There is a good chance they’ve been waiting for a release. Use this tactic when “Minor bug fixes” just won't cut it.
Take your bug fixing to a whole other level 🐜🎟
(I’m not sure how much value this has, especially to anyone outside of your organisation. But…)
Consider including ticket numbers for major fixes or releases. For this I would say, you either do this or you don’t. And don’t forget, consistency is key.
Upcoming updates…
Had to rush something out, but you know something big is around the corner? Tell the people it’s on the way!
Personalise
Speak to your audience. Personalise the intro or outro to break the ice.
🏔 Challenges and how to overcome them
Working for a large multilingual company, we face several challenges with release notes. Here are some common ones and how we’ve overcome them.
🏔 Many updates are trivial, under the hood or minor pixel adjustments…
Don’t write release notes in isolation. Start a collaborative document. Ask the designers and the developers to input also. Everyone has worked really hard for this release! No matter how small the user thinks it is. If you’ve put the effort in, the team will definitely have something to say about it. You can easily consolidate by summarising everyone’s input.
🏔 But sometimes, we need to release really quickly to bug fix…
…and that is fine. Super minor or boring bugs fixes can be called out as “minor bugs”. But have a couple of templated paragraphs in your locker for situations like this. Mix it up a bit to avoid repetition.
Now might be a good time to add some personalisation, or that feedback email address that I mentioned earlier 😉
🏔 But nobody reads app store updates!
With iOS and Android offering auto update features, it’s no surprise that the number of people reading app store updates is diminishing.
However if you’ve actioned this advice, you’ll have put some serious effort into your release notes. If that’s the cast, and you want to engage with your users, don’t wait for users to read the App Store!
Instead, tell them that there are new features available. SofaScores do a really good job of this by utilising the alert icon 🔴, guiding you to the “What’s New” page, which hosts all the update notes within the app.
All this work you’ve just put into formatting a release note shouldn’t go to waste. The same copy, and layout can be reused for internal emails, or in app “What’s New” updates. Withings keep the copy the same no matter if you view on the App Store or with their app.
The perfect release note template 🖋😍
Finally what you’ve being waiting for. How you piece all this together, and it’s broken down for you in nothing more than plain text:
The introduction. A short paragraph. Make this personal if appropriate. Eg. "Season greetings, everyone! You asked, Santa listened - this update is exactly what you ask for this Christmas."TL; DR
• An extra short summary of these notes goes here.*** NEW ***
• This is where you layout any new features.
• Explain where abouts these features are within your app.
• How do users find these new features?
• Which users will this benefits, or how exactly will this benefits them?
• E.g. "[Who benefits?] Apple Watch users will be particularly happy with the latest release. [Why?] We now automatically support handoff with your Mac. [Where/how?] Don’t forget to have your bluetooth turned on, you can do it]!"*** IMPROVEMENTS ***
• If improving an existing feature, rather than something that’s brand new, use the "Improvements" title instead of "New".
• If you've improved something as a result of user feedback, consider a sentence like, "you asked, we listened". A great way to make your users feel valued.*** FIXED ***
• List out any major bugs that might have affected many users.
• If you've only addressed minor fixes, or nothing specific, use something like:
• E.g. "Minor Bug fixes"
• Keep the "Fixed" title if you've included other titled sections.The sign off. Similar to the introduction, this could be personalised if appropriate. You could easily have a couple of variations of this in your locker.Finally Feedback. Add the feedback email address and welcome users thoughts. Eg. “Submit your suggestions for improvements to feedback@yourapp.co we value your feedback”
In Closing
A quote from my old boss, which has stuck with me for a long time:
The gap from ‘average’ to ‘good’ is big, people need to work very hard to get to ‘good’. But, to go from ‘good’ to ‘excellent’ it’s only 2mm extra distance. Yet people are happy to settle at ‘good’. They never know just how close they were to achieving something truly excellent — Danyl Bosomworth (based on Tony Robbins’ 2mm Rule)
Well formatted and well written release notes, are a great example of that 2mm difference. A difference that will help push your app from ‘good’ to ‘excellent’.
If you’re a designer reading this, go to your Release Managers and Project Owners with your understanding of typography and layout (not to mention the work you should be proud of completing), and help them reach that extra 2mm.
