Product Release Notes Best Practices: How to Properly Announce Changes

Product Release Notes Best Practices: How to Properly Announce Changes cover

What are release notes?

Release notes are a kind of communication that product managers or product owners use to let users know about new features or bug fixes. In other words, it’s the ‘What’s new’ bit that you can find on the product website, in an update email, or via in-app communications.

We distinguish micro, minor and macro releases.

The macro ones are normally fundamental changes to the product. These could be brand-new features that change the way the product serves the user or a complete overhaul of the user interface.

The minor releases involve incremental improvements to the product that make it better but don’t dramatically change the way users engage with the product. These kinds of releases are the key to product growth.

Finally, the micro releases included tweaks meant to fix bugs. Unless they’re extremely urgent, these are normally delivered and shipped in batches.

Release notes numbering
Release notes numbering.

Who is responsible for writing release notes?

Who writes release notes normally depends on the size of the company.

In a small start-up, this job could belong to the lead developer, while in a larger business it could be the responsibility of the product manager or product owner. In really large companies, writing software release notes can be a collaborative task involving product managers, the head of product, or the chief product officer.

The marketing or customer success manager may also play a role, for example, in distributing release notes. This is to make sure that customers know about updates and improvements to the product that will change the way they use the product.

Must have elements of release notes

Solid technical release notes should include these bits:

  • Header: with a date and number of the release and the product name. This is important for users to be able to identify which changes were introduced in what order and when.
  • What’s new: that’s where you introduce the new feature and functionality, update or bug fix.
  • Issues: the problems that you’re addressing in the release.
  • Solution: it’s important to highlight what you did to resolve the issue.
  • Impact: what the user needs to do to take advantage of the release, like installing an upgrade.

Top reasons users ignore your software release notes

While they play an important role in communication between the product team and the user, more often than not release notes simply get ignored. Why is that?

Your release note is too technical

Technical lingo is one of the reasons why users don’t read release notes.

If you’re using jargon and technical terminology or symbols in your notes for non-tech users, you might as well write them in a different language using a different script.

Not enough information that’s relevant

Release notes that are too general and don’t provide enough information to the user are useless.

If you writing about security patches or performance improvements, make sure you specify what exactly you’ve improved. Or don’t bother at all because your users won’t either.

Too many updates in one release note

You can make your product release notes too vague but you can make them too long and detailed too and that’s why many users will skip reading them.

Too much detail and text in general can be overwhelming. If the users can’t quickly take in the key points, you’ll lose them straight away.

Product release notes best practices

Now that we know why people don’t read release notes, let’s look at some release notes best practices that will help you make sure they don’t get ignored and, more importantly, help you communicate effectively.

1. Write release notes in plain language

Use simple language and avoid jargon.

Don’t write anything that you wouldn’t say in a face-to-face chat. Try to use the language that your users are likely to use themselves.

How can you get the tone and vocabulary right? Looking at the user feedback is a good way to dial it in.

Release notes best practices: Click-Up uses simple language
Release notes best practices: Click-Up uses simple language.

2. Keep information short and on point

To make sure you don’t overwhelm the user with too much information, keep your release notes simple, short, and relevant.

This one’s pretty straightforward.

Just use clear headings and bullet points to structure the release notes and make them easy to read.

Retool release notes have a clear structure
Retool release notes have a clear structure.

Write release notes using your brand voice

Your release notes should be consistent with your brand’s voice.

If your brand uses a fun and friendly tone, so should your release notes. Just because it’s a technical document doesn’t mean it has to be boring.

To get the tone right and consistent with the rest of your communications, it may be a good idea to involve the marketing team and their copywriters to tweak it when necessary.

Release notes best practices: keep your brand’s unique voice, like Slack
Release notes best practices: keep your brand’s unique voice, as Slack does.

4. Create your own release notes template and be consistent

Developing a template that you will use for all your release notes will save you time and ensure consistency.

Once they get used to the particular layout, it will be much easier for your users to understand them, so don’t change it without a good reason.

Release notes template
Release notes template.

5. Release notes should explain changes and set expectations

For the release notes to do their job, you need to explain what the update is and what it means for the user.

Make sure you give details of the change and, more importantly, the impact it will have on the user and their ability to get their jobs done.

The impact could be both positive and negative. If you’re introducing a new feature, don’t miss the opportunity to highlight how it will benefit the user. If, on the other hand, you’re sunsetting one, explain why and how you’re planning to make up for it.

The key in both instances is to set realistic expectations. Don’t overpromise as this will create a value gap and lots of disappointment in the long run.

6. Add images and videos to your release notes

Adding videos or images to your release notes will allow you to communicate more effectively.

Asana uses videos to enhance its release notes
Asana uses videos to enhance its release notes.

What’s more, visuals can be more appealing than plain text and have the power to excite users about the new features and make them eager to try them out.

7. Include relevant links and calls to action

While the release notes on their own should be brief, you can use them to communicate a lot by adding relevant links. For example, you can include links to the bug reports that the release is addressing.

Always include a call to action. If there is a new feature, invite the user to try it out.

What if the release is complete and can leave users confused? Give them the option to contact the support team.

userpilot-webhooks-release-announcement
Userpilot announcement-feature release.

8. Focus on what the new release means for the user vs the company

Write your release notes with the customer in mind.

Focus on what the new features mean for the user and not for your company. Show how the update will drive value for them and not for your business. It’s not a press release after all.

Amazon Business focuses on the benefits for clients in their release notes
Amazon Business focuses on the benefits for clients in their release notes.

9. Use multiple channels to distribute release notes

To reach all your user segments, use a range of channels to distribute the release note.

In-app updates

These are great to announce new features and updates to active users who use the product regularly.

Postify new feature announcement in-app
Postify new feature in-app announcements.

Sign-in page

The sign-in (or even sign-up pages) is another good place to distribute the release notes. However, its reach may be limited as regular users tend to save their passwords and choose to stay logged in.

Release announcement on the sign-in page
Release announcement on the sign-in page.

Blog post

Blog posts give you a chance to give more comprehensive information about the release.

Medium uses blog posts for their release notes
Medium uses blog posts for their release notes.

Email

Email, just like blog posts, allows you to give more detailed updates. It’s also to chance for your copywriters to show off their creativity to craft engaging content.

The key benefit of emails, though, is that it allows you to target inactive users or those that might have churned.

Release notes delivered via email
Release notes delivered via email.

Social media posts

Social media are a good way to reach your users. Your Facebook, Insta, or LinkedIn posts can also catch the attention of prospective customers.

Notion release notes on Twitter
Notion release notes on Twitter.

Changelog page

A dedicated section on your product web page is a good place to keep all the release notes in one place. In this way, your users can easily find them and track all the historical changes.

Help Scout changelog page
Help Scout changelog page.

Public roadmap

A public roadmap is not only a great way to show where your product is heading but also where it’s come from. And it gives you a chance to capture feature requests too!

A public roadmap with Atlassian updates
A public roadmap with Atlassian updates.

10. Use different content in your release notes based on the channel

Your release notes need to be tailored to the media that you use.

For example, your social media updates won’t be as detailed as a blog post or an email. You will also need to use a different style to catch the attention of the reader.

Sometimes a tooltip with a short gif is enough to deliver the message as long as you add the ‘learn more’ CTA so that the users can read the full release note.

Slack release notes on social media
Slack release notes on social media.

11. Make it easy for users to access all release notes: The What’s New Button

When using multiple channels to announce updates, make sure there is one central place where users can access all previous release notes.

And make it easy to access with a shortcut from the product, like Notion!

Notion makes it easy to find the release notes page
Notion makes it easy to find the release notes page.

Once you click on it, it takes you to the page with all the previous release notes.

notion-release-notes-best-practices
Notion release notes page.

12. Invite users to leave feedback

Once you release new functionality, make sure to collect feedback from your users.

How?

Build a feedback widget into your product so that users can leave specific feedback whenever they feel like it.

Miro allows users to give feedback whenever they fancy
Miro allows users to give feedback whenever they fancy.

Or trigger an in-app microsurvey as soon as users engage with the new feature to ask them about their experience.

Announce product changes with in-app release notes with Userpilot

How can you use Userpilot to announce new features and update releases in-app without dedicated release notes software?

Use different UI patterns to announce changes

Userpilot allows you to build and launch fully customized in-app communications to announce product changes.

It makes it dead-easy to create a modal or slideout that informs your users about the key changes. Sometimes even a small tooltip will do the job!

In-app announcements in Userpilot are great for introducing release notes
In-app announcements in Userpilot are great for introducing release notes.

To give users a chance to learn more about your release, include a link to the release note section inside your resource center where they access the detailed version anytime.

Get your release notes in front of the right users

Not all releases are relevant to all your users.

Some of your users may need that big modal right in front of their eyes to notice the new function that will save them lots of time. For others, a short personalized message about specific fixes to the bugs they’ve been complaining about is all they need.

Userpilot allows you to segment your users and target them with the right messages in the right format at the right time.

Userpilot allows you to target user segments with your release notes
Userpilot allows you to target user segments with your release notes.

Drive adoption for the newly released feature

Release notes are not enough to make sure that users adopt the new functionality.

To achieve that, you need to nudge your users a bit more. As a bare minimum, you always include a CTA encouraging them to take the feature for a spin.

Even better, if you include a link to a guide, webinar, or an interactive walkthrough that will show them how to take advantage of the new functionality.

userpilot-slideout-release-announcement
Educate users and help them adopt new features with webinars after product releases.

Conclusion

Following the release notes best practices will help you make sure your users are up to date with the latest updates.

More importantly, it’s your chance to show your users that you are listening to their feedback and increase their loyalty. Carefully crafted release notes can be also very effective tools for driving product adoption.

If you would like to see how easy it is to distribute release notes to specific user segments in Userpilot, book the demo!

previous post next post

Leave a comment