Release notes, also known as changelogs, release logs, revision history updates, .README files, or software changes, provide information about the features and enhancements of your latest product release.

Whether you're a technical writer or a project manager, it's likely that you feel a slight element of dread when it comes to writing your release notes. Release notes are often treated as an afterthought. In fact, a surprising number of software teams fail to communicate some or even all of their product changes.

However, release notes are user-focused technical documentation that showcase your team's hard work on consolidating and extending value to your users, and as such are a valuable opportunity to inform and engage your users in your product journey.

At UserVitals, you'll learn why release notes are so important, what questions they need to answer, how best to structure them, and how to share them with your users.  

Why Are Release Notes So Important?

If you work in product management, you've almost certainly heard feedback from your users asking, "When did feature X change and why?" This is where your release notes come in by acting as a direct line of communication with your user base.

Remember, your users want to see regular updates, upgrades, and fixes to your product. Not only do these changes help you stay competitive in the marketplace, but each sprint completion or release is a new opportunity to re-engage your users and attract new ones. Therefore, release notes are not only useful for your existing users, but for potential users as well.

These important communication touchpoints create transparency between your teams and with your users because they:

• Increase the visibility of product changes and new product features.
• Educate your users. New features can be confusing, and your notes are an opportunity to encourage feature adoption.
• Demonstrate your commitment to continuous growth and improvement.
• Set expectations and communicate product priorities to your users.
• Close the feedback loop by giving your users insight into how their feedback is used and why it's so important for product improvement.
• Encourage transparency and trust. Release notes are an indicator of whether what you're delivering is in line with your roadmap.
• Drive engagement by reminding your users of the value of your product.
  

What Questions Should Your Release Notes Answer?

First and foremost, your release notes inform your users about product changes. Specifically, they point out changes that affect the way existing or prospective users interact with and use your product.

These types of updates and upgrades include anything from a new product feature to an entirely new product.

With this in mind, when creating your release notes, you should aim to answer the core questions users have. For instance: 

• How is this product or the latest version of your product different from the last?
• What elements of your product have changed?
• Why have those elements changed?
• What impact do these changes have on me as a user?
• Are there things I need to do differently as a result of these changes?
  

Based on these questions, you can apply general principles that streamline the structure of your release notes. This will ensure that they serve their purpose of being both informative and educational.

How Should You Structure Your Release Notes?

Both users and developers should be able to find important information in your release notes about updates to your product and how they affect them.

The structure of your release notes should be designed to engage the reader. Ensure that your notes contain the right elements to make them digestible, easy to navigate, and engaging.

Include in the introduction of your release notes:

• Headline: include the name of your product, release number, and date.
• Summary: A brief description of what is covered in your release notes.
  

For the body of your release notes, follow this simple structure that highlights key areas of user interest:

• Start by focusing on what's new about your product.
• Then move on to improvements to existing features.
• Next, highlight bug fixes.
• Finish with operational updates such as server upgrades.

As you write each section of the release notes, make sure that each issue addressed includes the:

• Overview: a concise description of the problem and the steps to reproduce it.
• Solution: the adjustments made to fix the problem.
• Impact: the effects of these adjustments on the user, such as configuration changes.
  

Keeping your release notes well structured will lead to greater engagement from your users, but what else can help boost readership?

How Can You Keep Your Release Notes Engaging?

There's little point in writing release notes that no one reads, so it's important to engage your users in what you write.

1. Add visuals. The mind processes images 6,000x faster than text.
2. Keep it short. Make sure your descriptions are to the point and digestible.
3. Break up your notes by including links to more information. This allows you to keep the most important information at the top level while giving interested readers the opportunity to learn more. For example, include links to user guides or tutorials.
4. Make them concise. If your notes are vague, they don't provide the reader with context or a real understanding of what you've written.
5. Use headings that make it clear which notes are of interest to your users (e.g. bug fixes, improvements, new features).
6. Refrain from using technical jargon that might put off your audience. The key is to make sure your users understand what changes and updates mean to them. While some familiarity with software development terms can be assumed, you need to make sure that all updates are readable and can be understood by your average user.
   

Once you've written your release notes, the next step is to distribute them so that your audience can easily access and read them.

Where Can You Distribute Your Release Notes?

Sharing your release notes is just as important as writing them. You can do this by including links to your release notes, sharing excerpts, or providing the entire document.

There are many release note distribution channels to choose from:

• ‍Social media platforms: many SaaS companies will communicate their updates via Twitter, Facebook, and LinkedIn.
  

• Changelog widget: UserVitals offers you the ability to include a changelog widget on your website, which provides even more transparency around your release notes. With even leaving your website or application, your customer can view your product updates right on the same page.

‍

• Website: you can add your release notes to your FAQ page or blog. Or, through UserVitals’ Customer Portal, you can keep your release notes organized, and allow your customers to easily view the portal by clicking the link placed on your website.
  

• In-App Notifications: if your SaaS product is app-based, use push notifications to notify your users of changes. 
  

• Security or version updates: when your users update, it's the perfect opportunity to let them know what's new. 

• Email or SMS: include release notes in your newsletter and encourage users to sign up for update notifications. 

• App store: include release notes in your app bio. 

Ultimately, you want your release notes to be easy to find and up-to-date. Making your release notes public not only shows that you take user feedback seriously, but that you solicit further user feedback around your product.

Get Feedback on Your Release Notes

The goal of your release notes is to open up communication with your users around updates and changes to your product.

Release notes provide an opportunity to share the product changes that your users have contributed to, while also providing an opportunity to solicit further feedback from them.

Ask your users how they feel about the way you provide your release notes:

• Are the release notes helpful?
• Do they contain enough information?
• Are they able to find what they are looking for?
  

On the UserVitals Customer Portal, your users can discover your product's changelog and easily add feedback in the same portal.

When creating your changelog, it's an easy process that you can customize to your liking. Our descriptions allow for many different types of text formatting, such as markup, links, highlights, and headings - and you can even add hero images.

After your customers view your new product updates in the changelog page, they can add feedback by simply clicking the Give Feedback button found on the same page. This makes it a seamless process for your customer to add their comments, and they are only visible to your team. Use this changelog feedback to further understand how they like the update or how you can improve it.

‍

Release Notes Are an Essential Element of Your Feedback Loop. 

Release notes give your users insight into how their feedback and input was used to improve your features and product. They provide an opportunity to keep your users updated on the progress of your product and celebrate the deployment of features they have requested.

Learn more about how UserVitals can help you connect with your customers and keep them informed by joining our product demo today.