How to Write Knockout Product Release Notes For Your Startup

by Alex Wyatt in January 31st, 2022

Release notes are one of the best ways to keep your customers updated on your product's journey and new releases. Let's go over how they can help you and how to write the best release notes for your company.

What Are Release Notes?

Release notes are updates sent out with every new update or version of your product to inform customers about what has changed or been updated. Essentially, they're a user guide for your product's new release.

You may also see them referred to as a changelog or app updates; these names are often used interchangeably.

Why Are Release Notes Important?

Release notes can have several different important benefits for you. First and foremost, they help you set expectations with your users by showing them exactly what they can expect from your product. By explaining new updates in easy, clear language, you can make sure everyone is on the same page.

Likewise, changelogs are great for closing the feedback loop with your customers. While collecting feedback is important, showing where that feedback is going is important, too. Your users will want to see that the information they're giving you is helping your product, and this is a great way to do so.

Release notes and changelogs are also a good way to create a single, dedicated source of information for your customers to visit. Sifting through updates from different sources like Slack, social media and newsletters can be difficult and time-consuming, so it's important to make things as easy as possible for your users.

Having a dedicated source of information can also make things easier for your team as well by streamlining how you communicate with customers. Instead of having to release updates on all platforms, you can simply post them to one place and then link your changelog to other platforms if you would like to.

Lastly, your release notes offer an effortless way to showcase your product's development momentum, both to your customers and your investors. As you release new updates, your changelog will become a record of all product releasesessentially, it's a record of your product. You and others can look back on all of your updates and see how far you've come and all of the changes that have been made.

What to Include in Your Release Notes

Every release notes page is different, and you'll have to customize yours to fit your team and company. But there are a few rough guidelines on format and contents for each release.

How to Structure Your Changelog

The first thing to include in your release notes post is your header, which should include the product name, release number and date of release for clarity.

Next, you'll need to include a brief overview of what you're including in your release notes, including all new features and important info. 

Now, let's move on to what to do for each new feature included in your release notes. Each feature or issue should have an issue summary, which will give a short description of the bug or feature you're focusing on. Next, you'll want to describe what you did to address this issue (AKA the solutions), and how they will impact your product.

Some people also like to structure their release notes by the type of feature addressed. You can start by focusing on what's new, then moving on to improvements or upgrades on existing features. Next, you can highlight bug fixes and operational upgrades like server upgrades.

Remember: most customers will skim your release notes to find out what they are most interested in, so you'll want to get the point and make sure your notes are as readable as possible.

What Questions Should Your Release Notes Answer?

Your release notes are first and foremost for your users, so your release notes need to focus on what they need and want. Here are a couple of questions to help guide you:

  •  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?

Tips for Creating Successful Release Notes

We've collected a lot of tips on creating successful release notes over our product journey. Here are some of our best.

Distribute your notes across multiple channels

While your release notes are first and foremost meant to help keep your customers up-to-date on your product, they're also a great way to drive engagement to your site. Because of this, it's a good idea to distribute or share your release notes on multiple platforms.

Each channel has its pros and cons, and your outcome will be slightly different depending on which platform(s) you choose. Here's a quick run-down of the channels you should look into.

  • Email: emailing your user base can be a great way to re-engage users and bring them back to your platform to check out what's new. Email newsletters can be particularly helpful for this.
  • Blog Posts: some teams choose to rewrite their changelog entries into longer blog posts, which can be great for social sharing.
  • Social Media: social media posts that link to your release notes or individual updates can be a great way to summarize new features and drive more traffic to your site.
  • App Stores: app store updates can be great for succinctly summarizing any changes you've made, and then linking to longer release notes for customers who are interested in learning more.
  • In-App Messaging: in-app messages are a good way to notify regular users of updates to your product as they log in. 

While these are the main distribution channels many teams choose to focus on, there are many other ways you can share your release notes. For instance, you can link to relevant changelog updates in support pages or FAQs, or share them on online groups and communities like Slack channels, Facebook groups and LinkedIn communities.

Choose which channels work best for you, but don't overwhelm yourself; any channels that aren't helping your product are worth cutting.

Use In-App Messaging

We've already talked a little about in-app messaging, but it's worth mentioning again. Using in-app messages can be one of the easiest ways to link users that you already know are interested in your product to your changelog (as well as other areas of your app or site).

This can be via subtle pop-up prompts, or via a dedicated release notes widget. There are many apps that can help you set this up; for instance, UserVitals has a great changelog widget that embeds into your site and quickly summarizes your three most recent updates.

 Add product screenshots, videos and GIFs

Using product screenshots as well as videos and GIFs that show how your product works can be great ways to help showcase the changes you've made. Likewise, some of your customers may be more visual learners, and using aids like screenshots or videos can be the easiest way to communicate product updates.

 Group updates into categories

One of the most important things to keep in mind when putting together your release note documentation is organization. You'll need to find a way to sort and label your changelog entries so people can quickly find what they're looking for instead of having to sort through every update you have to offer.

One of the simplest ways to do this is by organizing your entries into groups. This can be by the area the update focuses onfor example, user interface or account settingsor by the type of release; for instance, you could sort by new features, product updates or bug fixes. Choose which format feels natural to you and fits best with your company.

Best Practices for Writing Stellar Release Note Documentation

We have a few more guidelines to help you write great release notes for your product.

Keep them brief

Let's be realyour customers don't want to read paragraphs and paragraphs on every change and addition you've made to your product. Time is crucial, and you'll want to make your release notes as concise and brief as possible to not waste any of it.

Try not to write more than a paragraph or so for every major update, or a few sentences for smaller updates. But make sure you're still getting everything across that you need to; the trick is to make sure you keep everything you need and nothing more. 

Avoid technical jargon

When you spend most of your time around people who use office or technical jargon to describe your product, it can be easy to pick it upno matter if you're working in development or simply working alongside them. Unfortunately, many of your users may not have the same background as you and therefore can't understand the technical vocabulary you do. This can decrease readership and alienate your viewers, doubly hurting your changelogs.

When writing your changelog, make sure you're writing as plainly as possible. It's a good idea to go through your changelog entries before you post them just to make sure you aren't using any terms your users won't be aware of. 

Show customers you care

Your customers will want to know that you care about keeping them happy and making sure your product works for them. Make sure they know that they are your focus when implementing changes.

Make them fun

We'll be the first to admit it: release notes can be boring. And that can keep customers from looking at them and getting the information they need.

You'll need to try your best to make your release notes fun and engaging. Try to think of unique or innovative ways to make your changes interesting, and try to inject your own personality and voice into your writing while still keeping it professional.

Get feedback on your product

Finally, one of the most important things to do to keep improving your release notes (and create a great feedback loop!) is to gather feedback on your changelog updates and your product in general. What updates are they excited about? Which ones do they think aren't necessary?

It's also important to take this idea to the rest of your app. Gathering feedback on how your customers are using your product will help you figure out what updates to prioritize and what direction to take your product in.

At UserVitals, we make collecting feedback from your users easy and seamless, without having to manually bring in information yourself. But let's talk about another of our best features: our changelog and release notes systems.

How To Write Release Notes With UserVitals

Our changelog tool is easy to navigate and makes creating your release notes page simple and pain-free. We format everything for you, so all you have to do is add in your changelog entries and organize them however you'd like.

Once you've made an account and opened our app, click on the Changelog tab in the sidebar. This is where all of your release notes entries will live, listed in chronological order.

To add a new entry, click on the New Draft button at the top-right of the screen. Once you've given your entry a title, you will be sent to the next screen where you can add in the details of your entry and add a hero image if you'd like.

Within this section, you can format your entry however you'd like, from adding links to text markup to different headings. You can also add labels and categorize your entries via type, like we mentioned earlier.

changelog 2

Once you've added all the information you want to your changelog entry, just click Publish and the entry will be added to your changelog page. You can add as many release notes posts as you like, whenever you want; this means you can backdate entries, or just add more when new updates come out.

Once you've published your changelog entries, you can also automatically send updates to your users so they'll get them directly to their inbox. We also have buttons for social sharing, so you can distribute your notes however you want.


 Learn more about UserVitals and what it can do for you today.


Your cart
    Checkout