If your company makes release notes, it’s important to remember that your audience is your user base. As your user base will be reading these informative documents, it’s important to remember that:
- They aren’t necessarily developers
- They need to understand how/why the change affects them (and in what way)
- They want to know if they need to do anything to initiate the change in order to benefit from the upgrade
Therefore, if your release notes are overly technical, and don’t explain to your audience why they should care, likely your release notes aren’t actually helping that many people.
The Do’s and Don’ts of Release Notes
If you’d like to get a sense of how to properly write an effective release note, keep these high-level suggestions in mind:
DO:
- Make your notes accurate, clear, and concise
- Be user-focused (position it from the user’s perspective)
- Give enough context so that the release note is understandable
- Explain if there is anything that needs to happen on the user’s end to make the change happen (for example, downloading the latest version)
- Use simple wording and phraseology – especially if some/all of your user base does not necessarily use English as their first language
DON’T
- Start with the fact an issue has been “fixed” (that’s implied)
- Write in an overly formal or impersonal manner (nobody wants to read something that is long and boring)
- Use language that is full of jargon or stylized language
- Don’t go into great detail or offer too much complexity (you can link out to docs for users if they want more information)
Release Note Writing Tips
When you are ready to begin writing your release notes, there are a few writing tricks that can help you nail the release note writing process. For example:
Use a Template!
Templates can be especially helpful if more than one person in your organization is writing release notes, or, if, in the future, you would like to hand the task off to another department/team member. Templates are also helpful as they begin to bring a cadence to the writing, and users begin to recognize the repeated patterns as well, making the entire note easier to understand. By having a predictable format, you’re not re-creating the wheel after every software update and that ultimately will help with writing regular release notes that a customer will understand.
As we discussed in a previous release notes blog, a typical release note may contain:
- A Header (document name, product name, release number, 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 a new 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.
Try scanning your favorite software sites and taking a look at their release notes to get a sense of how they template their work. Then, simply take the best parts and copy them to create a template that can be a part of you’re team’s own toolbox.
Talk About What A User Cares About!
Customers are coming to you with a “what’s in it for me” attitude. They don’t care if you fought for two minutes or two years to solve the problem for them, they just want to know:
- What was the problem
- How it affected them previously
- That is was fixed and how the update affects their user experience now
If you can lay out your release note to showcase exactly what you did for the user to make their experience better, you’re well on your way to writing an excellent and informative update.
Expand and Simplify!
No matter what kind of writing you’re doing, the reality is that you’re going to have to do some editing. The best way to tackle a release note it to expand on everything…then go back over what you have written and condense it down to the actual meat. It may seem like more work on the outset, however, trying to be concise in one go often causes release note writers to leave out important details and to make much less sense. Plus, when it comes to writing, it’s easier to cut down than to add bulk. Give yourself the time and permission to edit. No release note is perfect on the first draft!
Remember: release notes are a reflection of your company and create a new method of outreach to your customer. By creating easy-to-read notes that are transparent and helpful, you’re enhancing your customer’s overall experience when interacting with your brand.
Want to learn more about Bitband and how we help companies work better? Let’s chat.
Want more Bitband insights? Check out:
