When we think of release notes, we roll our eyes, remembering a dull side note met without enthusiasm by users. They’re a legal obligation that must be done, but they’re done without too much effort.
A little while ago, people used to buy products and software, and there was no evident feedback bridge between developers and users. Nowadays, the dynamics of product delivery have shifted to purchasing software weekly. A communication channel between the user and product becomes essential with such frequent product distribution. This channel is called “Release Notes.”
What Are Release Notes?
Release notes are a vital way of understanding the current state, see past updates and release versions. This document conveys upcoming features, changes, improvements, and enhanced user experience. In addition, it supports the process of maintaining end-user experience, user guides, and training materials. According to Wikipedia, “another abbreviation for Release notes is Changelog. However, in some cases, the Release notes and Changelog are published separately.”
Release Notes vs. Changelog
As already mentioned above Changelog and Release notes are considered as the same stuff. But some tiny nuances differentiate them. Many teams get confused about the difference between a changelog and a release note. Often, they are grouped together or used interchangeably to describe written alerts that tell a product’s latest changes.
Depending on your focus and marketing strategy, you can pick whatever you like.
Release Notes provide interactive connections with your audience, improving the product, and adding current features to your project.
Changelog offers a chronological list of the updates and serves as a kind of reminder of why this has been done. A changelog is the best way if you are focusing on bugs, technical details, and chronology.
Who Writes Release Notes?
It’s time to write release notes. Who should do it? You need the right voice to speak to different audiences, especially in a short update like release notes. It’s best to analyze internally within your team who should write release notes based on your audiences. Release notes are usually written by:
- Product manager. Product managers should have a fresh understanding of the deployed feature or release. By release day, they’re closely familiar with the changes. They’re often technical, strong communicators, and great writers. However, product managers are busy people. They don’t always have release notes on their mind. Release notes need to be timely. If the product manager cannot find time to create release notes, it might be the case for someone else to take them over.
- Marketer. Product marketing managers are usually great writers. They understand the need for timely communication, and they have a good understanding of the customers. They know the value of quality content. After all, release notes are a form of marketing. But, marketing teams don’t always have the strongest understanding of the product. They likely know how things work at a high level, but they might not be acquainted with things at a level where they can truly nail the details required for excellent release notes.
- Support specialist. Teams interacting with customers have a lot of empathy for them, and they’re usually great communicators. They understand the impact of surprising customers with mind-blowing changes. Customer support teams are very familiar with the product. Though, like product managers, customer support is pretty busy talking to customers, answering tickets, and troubleshooting bugs. This type of work never really ends; there’s always something to be done. This means release notes might not be the top priority here.
- Developer. If your release notes readers are most likely to be technical, your dev team is best to write in their jargon and share the details essential to their work with your product. Such a team is most likely to know how technical users will want to use different elements and react to various changes in your product. On the other hand, if your release notes readers are ordinary people, they won’t understand all this technical jargon, and developers rarely can write in a simple language.
- Technical writer. Now, let’s talk about technical writers. Technical writers are usually not found as a part of startups. However, if your product is more complex, you might need one. Technical writers are on board to ensure that your product documentation and its changes are done completely and correctly, covering even legal bases. Technical writers also help your team put out manuals for the use of your product, implementation details, installation guides, API details, etc.
How to Write Release Notes?
After we made up our mind about the release notes’ creator. Let’s see what should be included so that this document would be welcomed by the users:
- Title. Add the title of the new release. This might not necessarily be the name but just the version number or a specific name given to the update. The name should be short and memorable and convey what the update is about.
- Product details. Add the details of your company’s registered name, and the official name of the product. The reader should clearly understand which product is being updated in the release.
- Credentials. Add details about the credentials for the release version. What can users expect from the new release? How will it impact the current product and its users?
- Schedule. Indicate the date when the new version will be available to the public. If there is a beta version coming out, mention when it will be available and who will be eligible for beta testing.
- Details. Include the new features added during this release. Add images and videos of the new features to support the text. The readers should get an understanding of what the new features are so that they get excited to get the new release.
- Explanation. Explain what was fixed in the product. What problems were they causing in the past?
- Description. Describe the improvements made from the previous version. Show them what they’re missing out on in terms of things like speed, upload time, search capabilities, etc.
- Additional resources. Include any resource manuals that can substantiate the new features. These resources can be “how-tos” for understanding how the new features work, especially if they are technical in nature.
Release Notes Examples
If you’re still not sure that you’ll write an excellent document, here are some tips on how to write the best release notes and examples of inspiring release notes.
- Clarity is the key in your release notes. You need to find a balance between providing enough detail and not overwhelming users with big, confusing blocks of text. The people who scan release notes want information on what's been changed and how that affects them. So keep explanations short and simple, but don’t oversimplify. Slack didn’t feel the need to give every single detail of what the bugs were and how they were solved, therefore avoiding using complicated words, and managed to keep the notes short and interesting.
Source: Slack
- Keep release notes organized. Users will become numb when asked to read or scan a wall of text. Keep things organized and segmented using subheads, drop-down menus, bullet points, and paragraph breaks. Breaking up big blocks of text in your release notes will help the user readily find which change applies to them. A good example here is ClickHelp which has a dedicated release notes page. Each release has its own menu to segment changes by category.
Source: ClickHelp Release Notes
- Use visuals. Unsplash is a website dedicated to sharing stock photography that doesn’t have to update its services every week. So, they publish articles on their blog to inform regular readers about the new version. This method is probably the best that works for companies like this.
Source: Unsplash
- Demonstrate. Release notes don’t have to be limited by a blog post or support article. HubSpot created product spotlight videos that take their users on a tour of how the product has grown. You can watch the entire video to see everything new or skip to the sections you care about most with the handy timestamps below. Of course, this is done with more traditional, written release notes. They are there too.
Conclusion
Release notes represent an opportunity to communicate with your customer base.
But is that all release notes can be? Release notes can take on different roles in product marketing and serve a broader purpose. Your team can use release notes to increase engagement, build excitement around your entire product, and extend your reach to new audiences. Release notes are a robust sales and marketing tool, so who writes them is very important for who they are written. Don't cut corners on your release notes—they're your chance to share the culmination of your hard work.
Good luck with your technical writing!
ClickHelp Team
Author, host and deliver documentation across platforms and devices