Release notes are the way we let users know about changes in our application or service.
Unfortunately, users and developers often ignore them, and tech writers consider them one of the most boring types of technical documentation. So, obviously, I wanted to talk about them.
Something to get out of the way before starting is the usage of the term. We use release notes when you have different versions of a software or application. But if you are in a project that uses rolling release or continuous integration, you will usually talk about a changelog. The principle is the same: telling users about changes in your software.
In this post, we are exploring three ideas:
- Different types of products = different release notes
- Types of release notes
- Writing release notes that make sense
But first, let’s define who should write release notes.
Who should write the release notes?
This is something I want to get out there. Usually, technical writers are the owners of the release notes. That means that they have to make sure someone writes them, reviews them, and publishes them when the new release is out. But that doesn’t mean that the technical writer should be writing the release notes.
Depending on the team and how they work, everyone should be writing release notes. Product managers and developers need to understand what they are doing and the benefits the changes bring to the product, so they should start drafting the release notes.
That is why, before writing release notes for your project, you should define a process that makes sense and fits in the work methodology for your team.
For example, if your team uses Agile, include the Documentation and Release note for a new feature in the definition of done. I ensure you developers, product managers, project managers and other members of the team will be eager to help if this impacts their metrics.
Overall, documentation is a team effort and the technical writer is there to define what documentation the project needs, how to organize it, and make sure it follows the good practices.
As we all know, documentation is part of the product. Remember that code is a liability. The benefit it creates is the asset. And documentation (including release notes) is one way to tie those two, showcasing the benefits to the end users.
Different strokes for different folks products
Release notes are tricky business. They will be different if you are writing release notes for an app (like the ones you can see in the App Store or Play Store), a service (SaaS), or an SDK or API (to name different cases).
This difference comes from the different types of audiences. We deal with non-technical (end users) and technical (developers) audiences.
End users don’t want to read release notes. They just want to use your software.
That usually means that the end users that read the release notes are your most engaged users, who want to learn about new features. Because of this, release notes can be an excellent way to communicate with this audience, besides doing the usual release notes business.
An approach that has shown better results for regular end users is adding a call to action on the UI itself or showcasing the changes using UI overlays or tutorials. This and good UX writing can solve end users’ release notes problems.
On the other hand, developers usually read release notes (take this with a grain of salt), especially to find new features or to learn if there are any new fixes. This means that we can use our release notes to track our progress and as an opportunity to communicate and educate our stakeholders.
As usual, take into account your audience when writing release notes.
Types of release notes
The following table describes the types of release notes that I usually use. This is geared towards a technical audience, but can also work for non-technical users.
| Type | Description |
| Announcement | Used to inform users about changes in supported versions, updating software versions, or any other information that may impact users and does not fit in any other category. This includes mandatory migrations, scheduled disruptive maintenance, legal updates, or billing updates. |
| Breaking | Use for product changes that intentionally break the functionality of an earlier version of the product. Do not use Breaking for a change to the default value of a parameter, unless the change is likely to be disruptive. Use Changed instead. |
| Feature | A feature has been added to a product. Provide a short description of the feature and link to more information in the product documentation if possible. |
| Issue | When the product is not behaving as intended. Use if the issue has a potentially severe negative impact on customers, or if there is a way to work around or avoid the issue. Do not use Issue for intentional changes that are not backwards compatible. |
| Fixed | Use when an issue significant enough to have been included in a Known issues page or the release notes is fixed. |
| Changed | A change to the product or a feature that does not fall under one of the other release notes categories. Some examples: – A new version of a supported library is added. – Support for a new configuration is added to an existing feature. – Changes to a default value of a parameter. – Changes to names of features or UI elements that do not impact the code but may impact workflows. |
| Deprecated | Description of deprecated feature or product. Note that deprecated means “to be turned down at a later date”. The feature or product should still be usable, at the time of deprecation. When the feature or product is made unavailable, it typically would have been in a deprecated state for at least some releases. |
Remember to always group your release notes by type, and be consistent on how you organize them.
Note that using all types of release notes may be overkill, but you can pick the ones that make sense for your product and your audience. If you are writing for a non-technical audience, for example, writing an app’s release notes, you can get away with only using Announcement, Feature, Issue, and Fix.
How to write release notes
I use a simple method that works for technical and non-technical audiences. To write a release note:
- Introduce the feature. If the feature has a name, use it. Otherwise, introduce it to the audience.
- Describe the feature. The ideal description is one or two sentences long. Try to aim for that, but use more sentences if it makes sense.
- Talk about the benefit for the user if it makes sense.
- Link to the documentation, if possible. This also helps keeping the description short.
Following these usually leads to consistent, useful release notes.
Let’s try to overhaul this release note for the CapCut app in the Apple App store.
Another way to word this release note following the convention above would be:
| Features: – Text editing. Adds new options when editing and animating text. – Makeup effects. Adds various makeup effects you can use in your videos to always look on point. – New video export formats. Export files in MP3 and WAV formats, making it easier to share and publish your videos. – Video-audio sync. Makes it easier to sync video to sound, helping you edit multi-camera recordings faster. |
Note that we also got rid of the numbers. Numbered lists should only be used for a sequence of steps to be performed in order or when explaining workflows.
In general, some advice that may help you write release notes is:
- Define your audience and cater to them.
- Keep it short. One or two sentences long. Try to aim for that, but use more sentences if it makes sense.
- Link to docs. Include a link to the main documentation for any new or updated features. Make sure that the documentation is up to date before linking.
- Group items by version number or release date. Users want to know not only what changed but also when it changed. It may be even more important for technical audiences. If your project uses version numbers and they are user-visible, group the changes by version number. If a version number isn’t available, group the items by release date.
- Group items by release note type. Make it consistent across all your release notes.
- Use images or GIFs only when it makes sense. Release notes are not a marketing tool; they are part of the product documentation. If GIFs or other marketing-oriented graphics are needed, link to them from a release note.
- Describe current changes in a way that will not become out of date. Users may read the release note after the change. Avoid using “now” or “previously” because it won’t make sense if the feature changes several times.
How do you write release notes? What would you add or leave out? Do you have a set of favorite release notes? Leave a comment and let me check it out.
Thank you for sharing – I was in the midst of a heated argument with my dev lead as to who should own this task and the best way to tackle it, your article gave me great insights and allowed me to better explain the importance of release notes for our tool.