Release Notes Best Practices
Have you seen ABC’s weather forecast video on the morning show when Greg Dutra suddenly discovered his TV panel is a touch screen?
The mentioned situation is a prime example of an average user's awareness of your product's features.
Consider the amount of effort put into designing, developing, and testing both the hardware and software aspects of that feature. Part of the issue lies in user onboarding and education, which is beyond the scope of our current discussion.
However, a significant part concerns changelogs and release notes. These inform your users about new capabilities of your product, novel usage methods, and enhanced workflows.
How to Make Release Notes People Actually Want to Use
Let's face it: most release notes are forgettable at best.
Can you honestly recall the last one you read with genuine interest?
Or do they blur into a sea of "bug fixes and improvements"?
Choosing the right tone of voice for the next update and embracing some user-centric best practices can transform your release notes from an afterthought into a valuable communication tool for product adoption and lead for better user engamenget and product satisfaction.
In this article, we'll break the mold. We've analyzed real-world examples to create a comprehensive guide to writing release notes that people will want to read. We'll delve into crucial components, explore best practices, and even showcase real-world examples to help you craft compelling and informative changelogs that people would love to use.
What is the difference between release notes and changelog?
Launches, release notes, and changelogs are essential elements for communicating product updates and changes to users.
Changelogs offer a detailed, technical record of all modifications made to a product over time, catering to developers and power users. Release notes provide a high-level overview of changes and improvements in a specific version, focusing on user-facing features and benefits. Launches create buzz and excitement around significant product releases or new products, targeting a wide audience through events and presentations.
Let's explore the differences between these three elements:
Changelog:
Purpose: Offers a detailed, chronological record of all notable changes made to a product over time, across multiple versions or releases.
Audience: Often geared towards developers, technical users, and power users who need a more comprehensive understanding of the product's evolution.
Level of Detail: Provides a granular and technical account of the changes, including minor bug fixes, performance improvements, and development-related details.
Frequency: Updated more frequently, often in real-time or with each incremental change made to the product.
Format: Typically maintains a simple, chronological format, often as a plain text file or a version-controlled document in a repository.
Release Notes:
Purpose: Provide a high-level overview of the changes, improvements, and new features in a specific release or version of a product.
Audience: Typically written for end-users, customers, and other stakeholders interested in the highlights of a specific release.
Level of Detail: Summarize the most important changes, focusing on user-facing features, bug fixes, and enhancements.
Frequency: Published with each new release or version of the product, which may occur on a scheduled basis or as needed.
Format: Often presented in a polished, user-friendly format, such as a formatted document, web page, or email announcement.
Launches:
Purpose: Showcase significant product releases, major updates, or the introduction of new products to generate excitement, attract attention, and engage both current and potential users.
Audience: Targeted towards a wide audience, including existing users, potential customers, media, and the general public.
Level of Detail: Focus on the key features, benefits, and innovations of the product, often accompanied by demos, videos, or presentations to create a strong impact.
Frequency: Organized for major product releases, significant milestones, or when introducing entirely new products to the market.
Format: Often involve live events, webinars, press conferences, or online campaigns, supported by dedicated web pages, long blog posts, landing pages, and promotional materials.
Figma is a prime example of how to handle multiple types of updates. In their 'What’s New' section, they not only announce major updates but also educate users on how to utilize them. Their 'Release Notes' section provides a high-level overview of product changes. During their annual Config conference in 2023, they announced their expansion into the developers' market with the Dev mode. As you can see, there are many overlaps in the presentation of these new features, but they still manage to capture attention and segment their message effectively.
Product Updates Goal Types: F.E.S.T. model
Release notes serve various purposes depending on the product and its target audience. While the primary goal is to showcase what's new, different types of updates cater to specific objectives and user needs.
You might be bored with technical details in a daily-use messenger or laptop’s operational system. On the other hand, funny video jokes in API documentation may be inappropriate and frustrating.
Setting the right tone and goal for your release notes is crucial to effectively communicating your updates and engaging your target audience.
The F.E.S.T. (Featural, Educational, Strategical, Technical) approach can help you tailor your message to your users' needs.
1. Featural Product Updates
Showcase how updates benefit users and make their tasks easier, faster, or more enjoyable. Entertain users. Not many people care about yet another new button.
Tone of voice: Engagement is king. Impress with benefits. They are emphasizing how the updates make their experience better and more efficient. Good design, short and engaging explanations, and exciting videos. It’s better to be in a creative form.
Content: Highlight new features, improvements, and enhancements directly impacting the user experience and productivity. Include examples and use cases.
Target audience: End-users, including new and existing customers. Make readers into your product fans and who will share the update with their friends and colleagues.
Reader's reaction: I want to try this feature out!
Examples to check: ARC Browser, Telegram, Linear.
2. Educational Product Updates
Educate users about the product's features, best practices, and optimal use cases to help them get the most out of it. Those updates may not include a significant feature but a new product use.
Content: Examples, guides, and resources that help new users get started quickly and existing users discover advanced functionalities.
Tone of voice: Use an informative and encouraging tone, conveying that users can achieve their goals by effectively utilizing the product's features.
Target audience: New users just starting with the product and existing users wanting to deepen their knowledge and expertise.
Reader's reaction: I’ll read it to learn a new way of achieving my goals with the product.
3. Strategic Product Updates
Communicate the product's vision, roadmap, and competitive advantages to attract potential customers and retain existing users. Those things should increase the overall sense of the product's values and vision.
Content: Highlight significant milestones, partnerships, industry recognition, and the product's unique selling points.
Tone of voice: Use a persuasive and aspirational tone to position the product as a leader in its market and emphasize its long-term value.
Target audience: Decision-makers, stakeholders, and potential customers evaluating the product's long-term value and market position.
Reader's reaction: I should continue using/buy/pay for that soon.
Examples to check: Apple, Miro, Figma.
4. Technical Product Updates
Explicitly highlight the changes. Ensure that people read and understand the consequences and actions they should take. Provide precise information about version-related changes that may impact the product's functionality or compatibility.
Tone of voice: Use a clear, detailed, and accurate tone to convey the importance of the changes and the potential consequences of missing these updates.
Content: Write about updates in advance. Warn readers multiple times, providing details on API updates, deprecated features, breaking changes, and their implications. Include necessary actions users must take to ensure a smooth transition.
Target audience: Developers, system administrators, and technical users who rely on the product's stability and compatibility. This is also a good form for internal updates, such as sharing with your team what you’ve done.
Reader's reaction: I understand what has changed.
Examples to check: Stripe, Facebook API, Webflow.
Factors for the most exciting release notes and changelogs
Engagement:
How is it interesting to read updates for the target audience? A regulatory financial or medical product must be a fully described update. A modern end-user app should be fun and entertaining.
Encourage users to explore new features, participate in discussions, or share their experiences with others.
Readability:
Present release notes in a clear, concise, and easy-to-understand format.
Use bullet points, short paragraphs, and simple language to make the content easily digestible for users.
Jobs-to-be-done:
Evaluate how well the release notes communicate the practical applications and benefits of new features or improvements.
Provide examples or use cases demonstrating how users can leverage the updates to accomplish specific tasks or goals more efficiently.
Focus on the "job to be done" rather than simply listing features, helping users understand how the changes can solve real-world problems or enhance their workflow.
User Feedback:
Provide options for users to give feedback on release notes, such as emoji reactions, comments, or the ability to suggest new ideas.
Encourage users to engage with the release notes and share their thoughts. This will make them feel involved in the product's development and help them understand the value of innovation.
Subscription:
Make it easy to subscribe for updates.
Offers users the ability to subscribe to release notes through various channels, such as email, RSS feeds, or in-app notifications.
Personalization:
What is here, especially for me as an end user? Can I read updates on my requests? Or read about a particular product component?
Highlight changes most relevant to users, such as new features they might find exciting or improvements to their frequently used functionalities.
Each user wants to know if there is something personal to them.
Consistency:
Maintain a consistent format, writing style, and visual design across all release notes.
Consistency helps users quickly familiarize themselves with the structure and layout of the release notes, making it easier to find the information they need.
Multimedia Content:
Incorporate images, videos, or GIFs in release notes to better illustrate new features, changes, or improvements.
Visual content can help users understand and appreciate the updates, making the release notes more engaging and informative.
Visual Design:
Create visually appealing and well-designed release notes that align with the product's branding and aesthetic.
Use a clean layout, appropriate font sizes, and color schemes to enhance readability and user experience.
Delivery:
Ensure that release notes are delivered to users in a non-intrusive and easily accessible manner.
Avoid using disruptive pop-ups interrupting the user's workflow, and ensure that release notes can be easily found.
Navigation:
Organize release notes logically and intuitively, making it easy for users to find the necessary information.
Use categories, tags, or a table of contents to help users quickly navigate through the product updates.
Search:
Implement a search function within the release notes, allowing users to find specific information quickly.
Multi-channel:
Release notes should be available through multiple channels, such as email, web, and in-app, to accommodate user preferences.
Ensure the release notes are optimized for each channel and provide a consistent experience across all platforms.
Shareable:
Enable users to share release notes or specific notes sections with others easily.
Provide share buttons for popular social media platforms and allow users to copy direct links to the release notes.
Search Engine Optimization (SEO):
Optimize release notes for search engines, making it easier for users to discover them through web searches.
Use relevant keywords, meta descriptions, and header tags to improve the visibility of release notes in search results.
Frequency:
Publish release notes consistently and appropriately based on the product's nature and the target audience's preferences.
Proof that the product is alive and consistently maintained. New features arrive, and bugs are fixed.
Accessibility:
Ensure that release notes are comfortable to read.
Follow web accessibility guidelines, using proper heading structures and ensuring sufficient color contrast.
Optimize release notes for mobile devices, ensuring they are easily readable and navigable on smaller screens.
Actionable:
Include clear calls-to-action in release notes, encouraging users to try new features, provide feedback, or take specific actions.
Make it easy for users to access the new functionalities or improvements mentioned in the release notes.
Archive and Version Control:
Maintain an organized archive of past release notes, making it easy for users to access and reference older updates.
Implement version control to track changes if the product has a version, and it’s important to know what’s precisely related to a current version to maintain a smooth and predictable version switch.
Localization:
Provide release notes in multiple languages to cater to a global audience.
Ensure that translations are accurate and culturally appropriate and maintain the same clarity and quality as the original content.
Best Release Notes Examples
Ahrefs Release Notes
Ahrefs, a leading Search Engine Optimization (SEO) tool, offers a masterclass in crafting educational product updates. Their approach to release notes goes beyond announcing new features and instead focuses on teaching users how to derive value from their toolset. Learn more about the art of the Jobs-to-be-Done approach with release notes....
ARC Browser Release Notes
ARC Browser has reimagined release notes as a vital part of its marketing strategy and viral growth, utilizing personalized stories and impressive design. Instead of just sharing a new button review, they frequently share short stories about the decision-making process behind their features, often accompanied by engaging images or video explainers. Recently, they launched a sort of TV series about their product updates. ARC's approach to releasing notes is an excellent example of using them as a central part of a company's marketing strategy....
Figma Release Notes
In this article, we look at the "Release Notes" page, which offers more traditional release notes, focusing on single new features or improvements, providing a high-level overview of the changes and summarizing the most important enhancements....
Figma What's New
Figma is a collaborative web application for interface design. It's always very interesting and exciting to check its 'What’s New' announcements, as they are highly engaging and encourage you to try the new feature right away. That’s why, in this article, we reviewed the ‘What’s New’ page with the latest features....
HotJar Release Notes
HotJar's release notes serve as a valuable resource for users, explaining the improvements made since the last update and how they can enhance users' job performance. Each update is presented with instructions, various types of media, and clear calls to action to educate and engage users. Additionally, every update focuses on a single change, with detailed headings providing expectations....
Raycast Changelog
Raycast, a productivity tool for better shortcuts and a command bar, tackles the issue with exceptional update announcements that keep users informed and excited about the product's value. Learn how Raycast prioritizes user benefits, showcases practical applications, and fosters a feedback loop, making users feel included and part of the product's evolution. This approach effectively engages its user base and drives product adoption....
Stripe Changelog
If you manage a product line with multiple components or frequent updates, segmentation with tags and a user-friendly navigation system are crucial, as Stripe demonstrates. However, to truly excel, prioritize user-centric language that emphasizes the "Jobs-to-be-Done" these features solve. Additionally, don't underestimate the convenience of email subscriptions....
Telegram Release Notes
Telegram, a well-known messaging app, creates updates within its stories. These updates are short, entertaining, visual, and educational, perfect for presenting new features in a consumer-centric app. This document will teach you how to explain features concisely, scale the explanation, and produce release notes in 18 languages....
Get Started with Ducalis free changelog tool
We've analyzed hundreds of release notes, and one thing stands out: clear, informative changelogs lead to happier users. Inspired by the best practices in this article, Ducalis offers a free changelog builder tool:
