How to Write (Better) Release Notes in 7 Steps

For some businesses, release notes are the only way product enhancements are communicated to customers. For others, they’re a sideline, developed entirely separately from user communications.

But if you want to do more with less — if you want to improve customer retention communications without having to do a stack more work — your release notes could be an unexpected, but valuable answer. Especially if they’re well done.

Release notes document new features, enhancements to functionality, and bug fixes. They’re usually concise and fairly direct, and naturally assume a level of familiarity with your product. The process I’ve set out below should make it easy to produce good quality release notes for your product that meet that need for your business and your customers.

But, if you want, this process will also provide you with solid fodder for other release communications — like emails or blog posts or feature tours — that can help remind customers how committed you are to improving what you offer to them. And let’s face it, we all want to know we’re loved even after we’ve made a choice and signed up with a service.

Let’s see how this can work for you.

1. Be clear on your target audience, and the purpose of the notes

Who reads release notes? For some products, the majority of users will check out each release note; for others, it’s a very select, specific subset of the main userbase.

Once you know who you’re creating the release notes for, you can understand why they’re reading the notes. And that drives the next step.

The release notes for the product I work on aren’t read by anyone but a very small percentage of users within key client accounts. And they have very specific reasons for reading the release notes – some have internal documentation they need to keep updated, for example.

But for some products, the release notes are read by a large portion of users who want to avoid the marketing spin – who want to get to the heart of the product and hear direct from its makers. Knowledge like that won’t just inform what you include and exclude – it can impact the tone in which you write the notes, and how you present them.

2. Work out what they need to know

Release notes are generally expected to document what changes have been made in the current release of your product. So obviously, you’ll have an idea of what you need your readers to know about.

But it’s also important to think about what your readers feel they need to know about. For example, we document bug fixes in a way that ensures whoever reported or noticed the bug will be able to identify it in the list and know it’s been fixed. But we don’t go into depth on each bug fix, since no one needs (or, to be honest wants) to read all that information.

At this point, it’s also a good idea to consider when your readers will need access to the release notes. On the day of release? A week before, so they have time to review them? This will help you schedule the creation of release notes around the work of actually building and deploying the release.

3. Identify what you’ve done in this release

It sounds simple enough, but if you put a good process in place for this step, it will smooth the production of each release note.

For example, you might decide to have a shared document that your developers and product owners can update progressively as work’s completed, rather than at the very end, which can leave you trying to compile the notes in a rush.

You might also break that document up into sections that reflect the kinds of work that’s typically done—say, new features, enhancements to existing functionality, and bug fixes. This will make it easy to see at a glance whether everything in the release has been included in the document.

It will also make it easier to structure the release notes themselves than if you simply had an unstructured list of new stuff.

4. Decide what you need to include

As they’re contributing information to your release note document, your devs and product owners probably won’t be thinking about the end user. So when it comes to preparing the release notes, you’ll need to work out which bits of information to include, and which can be omitted.

I’m thinking particularly of bug fixes I mentioned above, but you may also have to balance the voluble contributions of some against the thinner contributions of others to the notes.

More words, screenshots, and detail about one feature or enhancement than another will generally be taken to reflect the relative importance or complexity of that item, so keep that in mind as you work out how deeply you’ll cover each item in the list.

5. Work out a storyline or messaging if you need to

It’s not always needed, but sometimes a storyline can help to put your improvements into context. I’m not talking about adding words for the sake of it here, or turning your nice, concise release notes into a marketing tool. What I mean is that the order in which you present your information can help users to understand the changes you’ve made. So think that through.

For example, a recent release note I prepared made mention of a facelift for the product, as well as a major feature addition. The facelift entailed merely cosmetic changes—it didn’t affect functionality of the locations of items in the interface. The feature addition was a much bigger piece of work, with bigger long-term implications for users.

Which would you cover first? We chose to open with the facelift, since that’s what users would notice first the next time they used our software. The new feature was listed after that, but contained more screenshots and detail. One of the reasons this made good sense was because the new feature looked significantly different than much of the rest of the app, so putting it in the context of a visual refresh allowed us to skip more discussion of that fact.

6. Draft your notes

Most users expect release noted to be direct and concise. They’re there to get the facts. That said, it’s probably best to interpret each feature or fix from the point of view of your target audience. What does it mean for them?

For example, a change to your app may make it easier for your support staff to set up additional user accounts for enterprise clients. What that means to users of the release notes is: it’s quicker or easier for new staff with those clients to get access to the corporate account. So put it in those terms.

7. Repurpose what you need for other communications

If they’re well planned and written, your release notes can act as a springboard for other communications, possibly directed at other user audience segments, to highlight what’s new in your product.

Once you’ve nailed down the release notes, it should be pretty easy to see what can be reformulated into in-app notifications or tours, used to review help content, and repurposed and developed into blog posts, newsletter items, and other retention content.

How do you develop release notes?

That’s it—not a difficult procedure, although if you have a number of moving parts in your production process, release notes can take some doing.

But if you produce good release notes, you can get much more out of the work you put into them. They can give you a real head start when it comes to communicating about changes to a broader audience than may read your release notes now.

Do you have a process for producing release notes? And do they play into your customer retention efforts? I’d love to hear how you do it in the comments.

Frequently Asked Questions about Writing Better Release Notes