Crafting Effective Release Notes

Software products are regularly improved and updated. To communicate these changes to the users of the product, each product release includes a release notes document. The release notes document provides an inventory of changes that a product user would notice or care about. Therefore, it is important to understand how to create well-written release notes.

This article provides an overview of release notes, their importance, and how to write various types of release notes effectively.

What are release notes?

Release notes provide a detailed list of changes that affect users of a product and are published with each release. Release notes typically include:

• Features that were newly added,
• Problems or issues that were resolved,
• Existing features that have been modified, and/or
• Features that have been removed.

Release notes are read by various people who interact with the product, such as:

• Product users,
• Customer success teams who support the product users, and/or
• Support agents who troubleshoot problems or issues for the product users.

Since release notes are read by a diverse audience, let's look at the significance of release notes in detail.

Why are release notes important?

Release notes play a critical role in various areas, such as user experience, feature adoption, enabling support, decision-making, and consistent messaging. Let's look at each of these in detail.

Enhancing user experience

Any product user would agree that remaining informed about the product is useful. Release notes enable users to understand and use new features and improvements effectively, which leads to an improved overall experience with the product.

Improving feature adoption

Users adopt features based on their awareness of them and how well they understand how to use them. Release notes are an educational resource that guide users through product updates and encourage them to explore and adopt features.

Enabling support teams

Beyond individual product users, release notes benefit the support teams too. Providing detailed information about changes and bug fixes allows users to self-help, which reduces the volume of support requests and consequently enables support teams to focus on more complex issues.

Facilitating informed decision-making

Though products are updated regularly, the timing of changes or the changes themselves might not align with the organizational goals or requirements of some users. Release notes help users make an informed decision. With the necessary information, release notes enable users to decide when to upgrade to the latest version of the product or adopt a new feature.

Consistent and accurate messaging

Within an organization, release notes act as a single source of truth for all cross-functional teams, such as developers, product managers, customer success teams, support teams, and technical writers. This ensures consistent and accurate messaging about product updates.

Types of release notes

Based on the type of update, release notes can vary in scope, purpose, and how they are written. Here are a few common types of release notes:

New Features

New features are new functionalities or capabilities added to the product.

When you write about new features, first describe what is new, then describe what the new feature does and/or how it helps the user in the present tense. Using the present tense clarifies that the feature is already available at the time of reading. End the note with a link to get more details about using the feature.

For example,
Real-time Collaboration: You can now collaborate on documents in real-time, enabling you to view changes made by others instantly. [Learn more]

Enhancements

Enhancements are major improvements to existing features that provide better performance, usability, or functionality.

When you write enhancements, describe the improvement or change, then explain how this change will help the user. Ensure that you update the corresponding product documentation and include a link to that at the end of your enhancement note. Since you want to focus on meaningful changes, do not document minor UI changes or other changes not visible to users (like code clean-up) unless the code change results in a behavior change in the product.

For example,
Enhanced Search Functionality: The search feature now supports advanced filtering options, allowing users to find documents more efficiently. [Learn more]

Resolved Issues

Resolved issues are problems in the product that have been fixed in the release. You can use this section to highlight fixes for issues that were raised by the user, were assigned critical or high severity by your product team, or were documented as known issues in a previous release.

When you write about resolved issues, describe the behavior that was an issue in the past tense. Then add a clear statement in the present tense to indicate that the issue has been fixed. It’s important to use the past tense to clarify that the issue existed in the past but the statement that it has been fixed in the present tense to clarify that it’s resolved now. It would be helpful to describe the new behavior, especially if the fix is complicated or requires an action from the user.

For example,
You experienced crashes when opening large files. This issue has been resolved. You can now open large files without experiencing crashes because the application can now handle large files smoothly and efficiently. [Learn more]

Deprecated Features

Deprecated features are features that have been removed or are planned to be removed in future releases.

When writing about deprecated features, explain what is being removed or replaced, when the feature will be deprecated (date, quarter, or year), and why. Providing these details helps users plan their next steps, understand the rationale behind the change, and how it will help them. If the removed feature has been replaced with another feature, include that information or provide a link to more information.

For example,
Legacy Reporting Module: The legacy reporting module will be removed in the next release (Q3 2024). It is being replaced by the new Advanced Analytics Module to provide a more robust and user-friendly reporting experience. [Learn more]

Known Issues

Known issues are problems that have been identified but not yet resolved. You can use this section to include the issues that have been assigned a severity of critical or high.

When writing about known issues, describe the issue and how it affects the users in the present tense. Include a workaround if available.

For example,
Intermittent connectivity in the mobile app: You may experience occasional drops in connection while using the mobile app. Restarting the app can temporarily resolve the issue.

Considerations when Writing Release Notes

Release notes are written in conjunction with the overall product documentation. They are not a standalone document but part of the overall product help documentation. Users will see the highlights here and then find more details in the product documentation. Therefore, it is important to align release notes with existing documentation. Here are a few considerations for a consistent user experience:

Documentation Links

Analyze whether any existing documentation needs to be revised or new documentation needs to be added. Add links to this updated or new documentation within the release notes.

Consistency in Terminology

Match the references and terms used in release notes with those in the corresponding product documentation. This ensures a seamless transition for users from the release notes to detailed help content.

Collaborative Review

Coordinate with product managers, engineers, customer success, support, and other stakeholders to review the release notes in a timely manner. This collaboration ensures that the release notes are accurate and provide meaningful information that aligns with user expectations and product capabilities.

Final remarks

Release notes are a valuable resource for users and product teams alike. Well-written release notes enhance the user experience, improve feature adoption, and facilitate informed decision-making. By taking a few additional steps to make release notes useful for users, release notes can inform, engage, and empower users, leading to a more positive experience with your product and a stronger overall user experience.