Introduction: From framework to practice
In the how to write release notes, we introduced a simple mental model for how to write release notes clearly and consistently. The idea was not to give teams another template to follow, but a way of thinking that reduces overhead and removes guesswork when it’s time to write.
This article picks up where that left off.
The framework stays the same. What changes is how much context and detail each release needs.
Rather than talking about the framework in abstract terms, we’ll apply it to a set of realistic SaaS examples. Each example represents a different type of release, from small improvements to larger, more disruptive changes. The goal is to show how the same three questions guide the writing every time, even though the final release notes look quite different.
A quick reminder of the framework
Before we dive into examples, it’s worth briefly restating the framework.
Every release note should answer three questions:
Why does this change exist?
- What actually changed?
- What does this mean for the reader?
You don’t need headings for each question. You don’t need to follow a strict format. You simply need to make sure all three are answered somewhere in the release note.
Example 1: A usability improvement
The scenario
An end-user-facing SaaS application has improved the performance of its dashboard. Pages now load faster, but there is no new functionality and no action required from users.
What this often looks like
Dashboard performance improvements.
This kind of release note is common, but it leaves users guessing. Faster how? Does it affect everyone? Should they expect anything different?
What this looks like using the framework
v12.8.1
We’ve improved dashboard load times to make navigation faster and more responsive.
If you use the dashboard regularly, you should notice pages loading more quickly, particularly when switching between views.
Why this works
Even for a small change, the release note still provides context, describes the change, and explains what it means in practice.
Small releases still benefit from clear context. Brevity works best when meaning is explicit. It doesn’t over-explain, but it also doesn’t leave the reader to fill in the gaps.
Example 2: A medium-sized feature update
The scenario
The same application introduces saved views, allowing users to customise and return to specific dashboard configurations.
What this often looks like
v1.8.2
We’ve added saved views to the dashboard.
This tells users that something exists, but not why it matters or how it fits into their workflow.
What this looks like using the framework
v1.8.2
Many users rely on the dashboard to track the same information every day, but recreating views manually can be time-consuming. With this release, you can now save custom dashboard views and return to them whenever you need. Saved views remember your filters, layout, and selected metrics.
If you regularly work with the same data, this makes it easier to pick up where you left off, without resetting your dashboard each time.
Why this works
The release note explains the motivation behind the feature, clearly describes what’s new, and connects it directly to a practical benefit. Users can quickly decide whether this change is relevant to them.
Example 3: A large, more disruptive release
The scenario
The application introduces a redesigned onboarding flow that changes how new users get started and how existing users invite teammates.
What this often looks like
We’ve launched a new onboarding experience.
On its own, this creates uncertainty. Users don’t know what changed, who it affects, or what they need to do.
What this looks like using the framework
v.2.6
As the product has grown, onboarding new users has become more complex, especially for teams inviting multiple people at once.
We’ve redesigned the onboarding flow to make it clearer how to set up your account, invite teammates, and get started faster. The new flow introduces guided steps and clearer explanations at each stage.
If you’re inviting new users, you’ll now see the updated onboarding experience automatically.
For a full walkthrough of the new onboarding flow, see the full guide in our help centre.
Why this works
For a larger change, the release note provides orientation rather than exhaustive detail.
For larger releases, a good release note guides users forward instead of trying to explain everything at once. It sets expectations, explains what’s different, and points users to deeper documentation where appropriate.
What stays consistent across all examples
Although these three release notes vary in length and detail, the underlying thinking is the same.
Each one explains why the change exists, what has changed, and what it means for the reader. What varies is how much emphasis each question needs, depending on the size and impact of the release.
This is what makes the framework useful as a mental model. It adapts to the situation without requiring a different approach every time.
By applying the same framework consistently, teams can write release notes that scale with the product, reduce overhead, and help users understand what’s changed and why it matters.
In the next article, we’ll look at how teams can review and improve their release notes over time, using feedback and iteration rather than one-off rewrites.
