So many software teams treat release notes as an afterthought, or even worse, they don’t think about them at all. They are often missed opportunities to show product development momentum, drive engagement, and set expectations with customers. Customers love to know about changes (both big and small) to your product. Read on to learn more about writing release notes and to access our release notes template.
Things to consider when writing release notes
Who is your audience?
Who’s going to read your release notes? Depending on who your audience is, you may want to write your release notes with a certain tone and include (or exclude) certain information relevant to those people.
Where are they being published?
Where will your release notes be published? In-app? Publicly? Via an email? Your knowledge base? A blog? Figure out the best place for your audience to consume your release notes. I’m personally an advocate of making release notes available in-app, and publicly available on a dedicated release notes page. Here’s an example.
When will they be published?
When do your release notes need to be published? The day of your release? The day before? Once a month in a “release notes roundup”? Timely release notes are important, and they can make or break a customer’s experience with your product. Make sure you have a plan in place to publish your release notes at the right time.
What will you include?
What exactly are you communicating in your release notes, and what exactly are you not communicating in your release notes? Figure out an internal system to know what’s changing so you and your team are ready to produce complete and accurate release notes. Use a release notes template so that you remember to capture each piece of information every time.
Who will write them?
Who owns the release notes? Product marketing? Customer support? Customer success? Product management? Multiple teams? Determine who owns the release notes so you don’t drop the ball, and so they’re written in a consistent way. Releases are exciting and important moments for you and your customers – building a strong team around your release communication process will ensure you’re giving your customers what they deserve.
Anatomy of good release notes
Title & Date
Release notes should include a title and a date. The title can quickly summarize what’s changed, and if it’s multiple changes, the title might simply be something like “November Release Notes”. The key here is to give your audience an immediate understanding of the rest of the content.
Releases come in different flavors: bug fixes, new features, improvements. A good set of release notes should be clearly labeled as to what type of release it is. If you’ve released multiple items that you’re including in your notes, organize the information by category. In other words, have separate sections for bug fixes, new features, and improvements. This will make your release notes easier to consume.
If you’re introducing a new feature, don’t just tell your audience about it, show them. Include images, or animated gifs showing your product in action. Good visuals will help draw attention to the content, and this can ultimately increase user engagement in the product.
Release notes aren’t a place to explain the ins and outs of the feature you just released. That’s what your knowledge base is for. When necessary – and it often is – link out to your help documents or a blog article with additional details.
No one is opening your release notes looking for a good novel to read. Keep them short and sweet, clear, and to the point. Make them easy to browse so that your readers can find the information they care about. Use headings, bullet points, number lists. Create your own release notes template to help guide you.
Introduce your brand’s tone and voice into your release notes. They don’t need to be completely dry (or maybe they do) – have fun with them if you can, and make them a pleasant read if that matches your brand. Most importantly, keep the tone consistent throughout your release notes.
If you have some changes coming soon, your release notes are a good place to mention that. The key with good release notes is setting expectations and keeping your customers in the loop on what’s going on with your product.
Release notes template
Release notes should include the following elements:
- Images or animated gifs (if applicable)
- Links to detailed documentation
- Version number (if applicable)
We’ve create a release notes template which is available here in a Google Doc.
Release notes are an important asset in the software development lifecycle. They show that you have your ducks in a row and that you care about your customers’ success with your product. Both external and internal release notes are often necessary. Consider modifying your Definition of Done so that you don’t forget to create release notes. They should be consistent and repeatable, and when done right, they will expand your relationship with your users. Use our template, or create your own release notes template to help guide you.