How to write release notes

When you think of release notes, you may think of those few bullet points you see right before you upgrade your iPhone to the latest and greatest iOS. Something along the lines of:

• Now supports Dark Mode
• Fixes an issue where using the unicorn Animoji while blinking your right eye causes a complete network outage
• Bug fixes

While Apple writes relatively sparse notes, they have the benefit of their size that gets the information about their releases into the press. Now while you may not have Apple’s PR power, you can still use release notes to communicate what’s new with your product.

Why write a release note

Before we get into what goes into release notes, let’s talk about why you should use them.

We believe that the customer is at the center of product development. Their feedback and your insights about their needs should drive your product strategy. But the relationship doesn’t just end when you ask them questions and they give you answers. To build an ongoing relationship with them, you need to stay in contact with them and let them know what’s coming.

The release note is an opportunity to let them know that they’ve been heard and that you’re delivering functionality based on what you learned from them. Doing this frequently, for both large and small releases, keeps this connection with your customers active and makes them genuinely feel like a part of the process.

The more you can commit to a cadence (i.e., biweekly, monthly), the more confidence your customers will have that you’re continually working towards making their experience better.

What to write in a release note

Like most things in life, the real answer here is, “it depends.” As you engage your customer base, you need to ask yourself:

• “How often?”
• “What do I need to say?”
• “Where do I need to say it?”

Publishing cadence

You can choose to post something when you have a notable release, or you can choose to post a note on a predetermined schedule, such as biweekly or monthly. If you wait for notable releases, you may want to ensure that you’re not only focused on major features as you’ll only post release notes every once in a while. You might try and make sure you have some kind of communication at least once a month (this doesn’t have to be all in the same channels).

How long or in-depth your release notes are may depend on how frequently you publish them. You need to be realistic about how much time you can allocate for this. For example, publishing a page-long blog post every week about your releases may prove to be too much. However, publishing a weekly set of bullet points may serve your needs.

Release note content

We saw that Apple likes to take a pretty concise approach, but we also know that Apple communicates their updates across a variety of channels (super helpful to have a bunch of bloggers that cover you full time).

Regardless of channel, you’ll want to have some kind of versioning or timestamp for what you’re releasing. For an app, you might call it by the version name (i.e., v3.3.6). For a SaaS product, you might reference it by the date (February 2019 release).

Some advice out there will say things like “be brief” or “avoid jargon,” but those guidelines may not work for you. Remember, you’re talking directly to your customer base here, so don’t worry too much about marketing and copy. If you’re releasing an update to your FinTech API service, you’re very likely going to need to get jargony. Go ahead and talk about rate limiting those chargeback requests.

For information about bug fixes, simple bullet line items are good enough to let your customers know what you’ve fixed.

For our updates, we like to show how to use our new features, so we go in some detail as we describe them. However, there’s no need to write when video or GIFs will do the trick. As many writers often say, “show, don’t tell.”

Channels

Welcome to the modern-day internet where there are so many ways to get your note out there. But be careful not just to copy and paste the same information across all the channels you use. Email, blog posts, and a wiki/knowledge base are great for longer and more informative updates while social media posts are better for conveying a single release update.

Using your blog or wiki can help you with SEO optimization, and you can update as frequently as you like. Email is a great way to make sure the information gets to your customers, but you’ll want to keep on eye on the frequency of those communications. Whichever channel you use will depend on where your customers are and what resources you have available.

If you use an in-app messaging tool, like Intercom, you can post your release notes there in a concise enough manner to that fits into a chat message. You can also include a link to a longer blog post if you need to. In-app messaging is also useful if you want to target a subset of your customers.

Is it helping Support?

One way to know whether you’re writing the right kind of release notes and putting them into the right place is to check in with your Support and Success teams. Are they getting a lot of questions about the latest releases or are customers wondering why the product is now doing some fancy new thing they didn’t know about?

If so, find a way to tweak your release note content and process to minimize the number of questions going to those customer-facing teams. Once you accomplish that, be sure to soak in their praise and accolades because your customers clearly dig your release notes.