Release notes: Types, forms, and style

Release notes stand for a news presenter of your product. They might have various forms and types but obviously play a central role because how else will people know about your updates?

Purpose, role, and importance of release notes

The benefits of having release notes are the following:

• Users have better engagement with your services if they observe continuous growth in terms of new features.
• Users wait for releases because of the requested fixes or known issues. Listening to users’ feedback and meeting their needs is a proof of loyalty. Regular and constant improvements help in building trust.
• Users must be familiar with updates not to break their processes, infrastructure, or flows, especially having integrations with other tools: the versions of integrated apps might not coincide with yours.

So, the list means that whether you are into the e-commerce or software industry, product management, or technical communication, use release notes to reach your users.

For this article, I will share my experience and research results in these three cases:

• Smart home devices
• Source control tool available for integration with other on-prem and cloud solutions
• Music mobile app

Distribution channels

Thinking about the location for release notes, the following idea comes to my mind: rely on the type of your product and the spots users visit most.

If your company represents a mobile or web app, try the built-in notifications describing only the crucial changes or redirecting readers to the detailed release notes version.

If you deal with desktop software products and you know that this is where your users reside, you might send emails with main highlights and the link to the release notes page. I recommend locating the page close to the getting started guides or on the main level of your table of contents. What’s New is a good name for such section.

Social media announcements about major updates and new features also belong to effective distribution channels. Though, do not overuse such communication channels for minor patch releases.

And as for the blog posts, use them for storytelling — to provide an extended explanation or background for main changes.

Oftentimes, release notes are stored in parallel in several places. Music mobile apps store them on the website and App Store/Google Play Market. Source control tools usually store them on the website and a GitHub repository with integrations and packages.

Structure of release notes

To disclose progressively what you have to say about your updates, the structure varies depending on your product needs and the chosen distribution channel. However, let’s look at the list of the most common items to include:

• Title: Release Notes, Updates, Introducing [feature], and others
• A brief overview of the product, especially for a new product or the first release notes
• Release version or date of update
• Links or attached packages and files required for app work
• Compatibility with systems, including versions
• Known issues (if any) that will be fixed in the next releases
• Notable Changes and New Features
• Enhancements and Fixes
• Useful Resources or any sort of additional information with links

Nuances of style

Now — style. This topic is usually subjective. However, there are a few general best practices.

• Follow the tone of voice and cherish your brand and product standards manifesting consistency among other types of documentation and content.
• Choose your preferred ways of communication: pop-up notifications, banners, overlays, email newsletters, pages with interactive content, images, GIFs, and videos, or static view with text only.
• Remember about inclusiveness and accessibility. Strive for your release notes to be versatile — readable, scannable, and understandable for every user of your product. Add the alt text for pictures and diagrams.
• Keep everything organized and well formatted with TOC (for long materials), headings, bulleted lists, and tables.
• Rely on your expert audience, but as a golden rule says, describe the terms in human language. Leave the techy wording and jargon aside. You might start with a product-specific statement and explain the rest as generic: Smart Vision Console III: detect and control open windows. Remember to state an update, fix, or new feature from the user’s perspective — what’s in it for them?
• If your product is oriented to specific expertise, user types, permissions, or services, mind the diversity and distinguish them: Database Administrators now manage the hidden configurations.
• Don’t ramble, be succinct. Try to present the update in as few words as possible. But if the update is very complex, provide more details (still not too many).
• Specify the reason: Removed the confirmation message to sign in promptly. Same for the before-after structure, which is frequently beneficial: The free version showed an unlimited number of advertisements while listening to music. Now, the limit is three.

Release notes tips

If you are new to release notes, look through these five extra tips:

• When drafting the first two or three release notes, start preparing them beforehand (2–3 weeks ahead because you need to take updates from all corners) to have a template fully agreed upon with your colleagues.
• Decrease the amount of manual work, for example by configuring filters and labels in your Task Management system. They will identify and group updates belonging to the upcoming release. Another option is to track the product roadmap and pull information from there. You can try whatever suits you best!
• Be on the same page with all the teams participating in the release (Engineering, Product, Marketing, and others). Communication is the key to success.
• Be conscious about your inner company changes like code enhancements and changes for users: Added the System.out.println Java method vs Added the print command to track if your system is working with needed integrations.
• Keep your documentation up to date. If the known issue is no longer an issue in a new release, update the guide and be mindful of versioning. I bet you’d rather have a schedule of maintaining docs!

All things considered, stick to the main rule of technical documentation — put your users first, and the process of writing along with the outcome will go smoothly and be a success.