Every company releasing software updates should have release notes – technical documentation that outlines recent changes, features and enhancements, or bug fixes. Typically, the job of drafting release notes falls to the product manager – who may or may not be much of a wordsmith.
However, release notes are essential as they explain to a user how issues have been fixed or what features have been added. If written confusingly, it will only confuse and frustrate your end-user – something no company takes pleasure in.
As an aspect that is often undervalued, not much time or energy is given to making release notes, well, good. This is why companies have so much trouble writing them. And yet, they provide a valuable connection to the client and give your company a unique opportunity to speak directly to the client and the broader market, giving you a great way to nurture engagement.
Many companies waste this opportunity with bed release note habits that can turn users away. Here are five popular bad habits companies have when approaching their release notes (and how to fix them).
Five Bad Release Note Habits
Notes are Hard to Understand
One of the biggest faux pas a release note writer can make is creating a release note for a user that is hard to understand. They may be full of technical language or jump around without much care for the user that may not be a technical person themselves.
The Tone is Too Formal/Abstract
Many release notes read like a dry term paper. The writer treats the document like a “report” and may come across as much too formal.
The Release Note is Wordy
Some release note writers get into the weeds and go into every detail imaginable in the notes, oversharing information that can confuse a user and bury the lede.
There’s Not Enough Explanation
Release notes may also go in the other direction and not share any detail whatsoever in “what” was fixed, let alone getting into the “how” or the “why,” leaving a user to wonder how the fix or release affects them and why they should care at all.
The Tone is Too Jokey/Informal
Some companies use the release note as an opportunity to be a bit too jokey. Notes can have everything from stylized language to casual slang. While a certain level of fun casualness in language may work for a specific subset of users, if a company has a large user base – or an especially international one – language barriers may cause the inside jokes and stylized prose to fall flat.
How to Fix Bad Release Notes
With the above issues in mind, the next question is how a company can fix their release notes to make them accessible. Here are a few suggestions:
Make Them Easy to Understand
The first thing a company needs to do is ensure that the release notes are easy to understand. That means cutting out the technical language and writing from the perspective of a user. If your users are non-technical, it doesn’t make sense to get into the weeds of the technicalities themselves. Keep it high-level and straightforward, and use clear, concise language.
Talk Directly to the User and Explain Why it Matters to THEM
The whole point of issuing release notes is to alert your users to changes and fixes – presumably because it affects them.
Spell Out The Change
Don’t be shy; spell out exactly why and how the change helps the user.
Lay It Out Logically
Be sure to layout the change in a logical manner. Explain how it worked before, how it worked now, and why that’s beneficial. (i.e., Before when you did X, Y happened. Now, when you do X, Z happens. This makes A easier.)
Get to the Point
Be short and concise. Say what you need to say in as few words as possible without getting too vague.
Don’t Add Barriers to Understanding by Playing with Jargon
Remember that not every user is fluent in English or uses it as their first language, and not every user will get your inside jokes or appreciate your laid-back language choices. Since your product is already likely technical, making users struggle to understand your release notes likely won’t win you many fans.
What Should Be in My Release Notes?
While release notes don’t come in a standard format, they should follow your company’s standards. Whatever you do, consistency is critical, and it’s a good idea to “template the process” to make it easier and keep the information contained in your notes generally the same.
A typical release note will contain:
- A Header (document name, product name, release number, and date)
- An Overview (a short description of the product, feature, update, or fix)
- Purpose (what is in the new release)
- Issue (a description of the bug/feature)
- Resolution (modifications made to fix/add the feature)
- Impact (specific actions needed by a user or the effect of the changes and any functionality adjustments)
- Support Impact (specific changes that are needed to administer the software)
- Disclaimers (if applicable)
- Contact (contact details for support requests)
However, some release notes contain more or less detail, according to the company.
Don’t forget – release notes are a reflection of your company. By treating them as another avenue of outreach and customer service, you’ll be doing your product and your clients an excellent service.
Want to learn more about Bitband and how we help companies work better? Let’s chat.
Want more Bitband insights? Check out:
