> In contrast to release notes, which aim to be exhaustive, release announcements include only the most impactful changes.
No, don't do this. Provide release notes, not release "announcements". Exhaustive is good; exhaustive is helpful to the reader. Let them know their "little" bug is fixed. Or maybe if you accidentally introduced a new bug with your change, or affected the user's workflow in some way, the reader can figure that out too.
The entire blog post is about how to corrupt release notes with marketing.
You don't have to sell your software to someone who is already using it. That's just annoying.
As an indie developer, my users say that they appreciate my exhaustive release notes.
I remember back when I worked for someone else, my boss always changed "fixed a crash" to "fixed a rare crash" in the release notes (whether or not that was accurate) LOL. Keep management and marketing away from the release notes if possible.
>> In contrast to release notes, which aim to be exhaustive, release announcements include only the most impactful changes.
>No, don't do this. Provide release notes, not release "announcements". Exhaustive is good; exhaustive is helpful to the reader. Let them know their "little" bug is fixed. Or maybe if you accidentally introduced a new bug with your change, or affected the user's workflow in some way, the reader can figure that out too.
They're not mutually exclusive. You can publish both release notes and a release announcement.
>You don't have to sell your software to someone who is already using it. That's just annoying.
I really disagree. I'm guessing you mean "sell" as in "manipulate" but I see it as "get users excited."
Of the software products I use and pay for, I appreciate it so much more when the vendor takes time to write a release announcement with care and focus on user needs. When I receive release announcements from Tailscale or Fly.io, I don't think, "Oh, boy, they're just trying to sell me something." I think it's cool that they're putting in the effort to showcase their work.
When vendors just publish a terse changelog, it feels like they don't care much about me and couldn't be bothered to present their work to me in a more accessible way.
> They're not mutually exclusive. You can publish both release notes and a release announcement.
Where, though? Consider the App Store, for example. You can have releases notes or a release announcement in the App Store along with a new version of your app, but not both.
The way you present it, with "good" vs. "bad", suggests that you're arguing for one, not for both, for release announcements instead of release notes.
> I'm guessing you mean "sell" as in "manipulate" but I see it as "get users excited."
But users don't need to get excited by every software update. That sounds like your need to get users excited about updates.
> When vendors just publish a terse changelog, it feels like they don't care much about me
That depends on what you mean by terse. "Bug fixes and performance improvements" is terse and careless. A comprehensive list of changes is not necessarily terse. And in a sense, "release announcements include only the most impactful changes" is terse too.
The company I work at is at a sufficient size that we publish changes internally to other teams.
We have the concept of Release Announcements that are a quick attention grabber headline, followed on by Tasting Notes that explain in detail what changed and additional release notes.
That way the people who just want to understand the primary changes and those who want the details are happy.
Why not both? I think there are 2 purposes here. One is advertising for sure, and also light entertaining reading for interested users who want to keep up. The other is what power users will read through for their favourite change.
I still remember the time I got paged during thanksgiving for a platform wide outage and debugged the issue down to a python library that had been updated a few hours before with the patch notes saying “Nothing Significant”
Stopped reading at the graphic. None of those descriptions for dishes sound anything like what a developer would write. Just pure obscurantist nonsense. "Cow secretions" to refer to cheese? Really? Even though that's more ambiguous, wordier, less helpful, and less descriptive? The author tells on their own shoddy writing skills. A developer might be guilty of writing "Pizza - goat's milk mozarella, wood fire oven" instead of "Cheese pizza" but certainly not that nonsense.
Actually, I don't love this. To me, the examples in red are much more helpful -- they explain, in bare terms, what was actually done. The examples in green feel like a marketing exercise to me. Like they're trying to wrap or obscure clear writing in something to obfuscate it.
"Added 'duplicate' button to the event menu" is kind of exactly what I want to read.
I don't know -- maybe have both kinds? A simple, bare-bones set, and then an... "embellished" set?
I think there's a middle ground here that would be best. The "bad" example tells you exactly what changed, but not why you might care. The "good" example attempts to give lots of context but takes a while to tell you what actually changed.
Just a small title change would help a lot: "Create events 10x faster with new Duplicate button"
Just to add a nit to this, “10x faster” is noise and fluff. Save it for when you actually have a real measured metric that someone might care about. Notice also 10x faster generic event creation is not what the value is! Rather say “Make multiple similar events faster with the new Duplicate button”
>To me, the examples in red are much more helpful -- they explain, in bare terms, what was actually done. The examples in green feel like a marketing exercise to me. Like they're trying to wrap or obscure clear writing in something to obfuscate it.
Oh, interesting. That surprises me. I think there are some cases where I want the short version (e.g., if I'm just looking for breaking changes or fixes to minor annoyances), but I generally think the release announcement does a better job at showcasing features.
Out of curiosity, do you find the example changelog-style announcement[0] more useful than the Figma's example release announcement[1]?
>I don't know -- maybe have both kinds?
Yes, absolutely. They're not mutually exclusive.
Whenever I've published a release announcement, I also link to a changelog, which is the bullet point list of changes. I think the changelog should also be more user-oriented than most currently are, but I think the changelog is the right place for an exhaustive list of anything that users might want to know about the new version.
> but I generally think the release announcement does a better job at showcasing features.
I'm all in skimming some bullet points on release notes but reading whole paragraphs for trivial announcements (like "Create events 10x faster") is an absolute no-go and wasted developer time in most cases.
Agreed. And for me that has nothing to do with announcement vs. notes.
"We sped up new file creation, so you can now create a new file in under 20ms, a 100x speedup from v1.2."
No. You had a big bug. You fixed it. Excellent. When I'm affected by the bug I'd search for "deadlock" or "bug " in the announcement and this is hiding it behind marketing speak. I don't think that's honest. So for me the perfect announcements would be the red ones.
>"We sped up new file creation, so you can now create a new file in under 20ms, a 100x speedup from v1.2."
>No. You had a big bug. You fixed it. Excellent. When I'm affected by the bug I'd search for "deadlock" or "bug " in the announcement and this is hiding it behind marketing speak. I don't think that's honest. So for me the perfect announcements would be the red ones.
I'm confused about how you'd know to search for those terms unless you were part of the dev team of that product.
A hang in the UI could just be the backend doing work in a way that's not optimized for UX. It's not necessarily a deadlock or a bug. Those are implementation details. It's not something a typical end-user can perceive just by using the software.
Your article is well done with great advice. I definitely agree that we should focus on how changes benefit the user, not just what was built.
One positive criticism: in my case (with a small user base of aprx 100), I feel it leans a bit too much into marketing. My users often want to know that a specific bug has been fixed. Release notes aren’t just about excitement, they’re also about trust and value.
Saying “Saving large files is now 10x faster” is great, but if users were dealing with crashes or freezes, it’s more helpful, and more direct, to combine your idea of clarity with the actual user experience:
“Saving large files is now 10x faster, no more freezes for files over 100MB.”
Being transparent about what was broken and now fixed is important.
Also, not sure if the article is focusing strictly on public-facing release announcements. I find it helpful to maintain a more detailed, separate internal changelog for future reference. That includes technical fixes, implementation notes, and lower-level changes that aren't relevant to users but are valuable to me.
That said, I mostly agree with your approach, and I think your method works really well for major or long-awaited feature releases.
Overall it's a good article and please take any of my feedback with a grain of salt, as my experience is mostly limited to a small user base and not large-scale or widely publicized launches.
>Saying “Saving large files is now 10x faster” is great, but if users were dealing with crashes or freezes, it’s more helpful, and more direct, to combine your idea of clarity with the actual user experience:
That's great feedback. I'd like to come up with a better example here.
I've noticed that when developers improve user experience, they tend to focus on what was bad rather than how it's now better, but I agree that the example is a bit confusing. If the fix is about a bug in a specific scenario, you do lose something in the announcement by not explaining how you fixed that particular bug.
> I was embarrassed that the release primarily made life better for our developers rather than for our users. Given the tasks I planned for a sprint, I identified the ones that would be exciting and valuable enough to the user to include in the release announcement.
> I thankfully avoided ever writing another uncomfortable explanation of a release that offers nothing to the user.
Seems short-sighted?
This is marketing-driven development where you have "learned the lesson" that thankless maintenance and stabilization tasks should be avoided.
I got the same impression, not having a snappy marketing tag line is nothing to be embarrassed about.
Sometimes users just don't get it - and never will. Sometimes things are too technical to be useful to a user (the author touches on this themselves). Let the results speak for themselves - and be proud of your achievements, it sounds like this was a success.
Focussing too heavily on user facing issues is a kind of myopia that actually leads to a worse user experience over time, and, ironically, a slower turnaround for those user facing issues.
Considering the release announcement as part of sprint planning doesn't mean eliminating maintenance work. The release announcement is just the top N user-impacting changes in the release, so not every bit of dev work requires justification to the end-user.
The lesson I learned was that when I have a maintenance-heavy release, I needed to ensure that we have at least some work that's user-facing that we can present to users in the release announcement.
I would call this release marketing, not release anouncements, as it sounds more like ads than actually useful information. I do believe there is a sweet spot between release notes and release advertising, the true release announcement, but it needs to be more subtle.
I agree with the principle that you should tell the user what matters, but theres a tension between that and making it too long.
Every word is an opportunity for the reader to stop reading. Once they get a sense you're droning on, they'll stop.
To take the first example the author says needs fixing:
Added “duplicate” button to the event menu.
I think a better fix than the one in the article is:
Create events 10x faster
When you create a new event, first you copy/paste text from another event. This is slow, so we built added a "duplicate" button, You can find it in Options > Duplicate.
```
For reference here's the one from the article:
Use “Duplicate” to create events 10x faster
When you create a new event, chances are that the first thing you do is copy/paste information from an existing event. Creating events this way is tedious and slow, so we’re sparing you this toil with the new Duplicate feature.
When you need to create a new event based on an existing event, go to the existing event, and select Options > Duplicate. Duplicating events is 10 times faster than copy/pasting fields.
> Plan your release announcement during development
this little section gives me so much... dread.
on one hand, you have to be able to sell what you do; and on the other hand, if you cannot really quantify reasonable improvement to end user experience, can you really justify spending time on it?
we're basically back to figuring out how to allocate for "maintenace" that does not really translate to good "user story".
Yeah, this is something I struggled with as well. It didn't prevent me from allocating time to maintenance, but it meant I had to plan it more carefully. If I had a maintenance-heavy release, I made sure that we were including some "delighter" features even if they were small.
Great post, this is so true. We pay a lot of attention to the release emails we make. They are important documents that that explain the value proposition of the app.
We often select 3 items and spotlight them in order of priority. So there is also an element of selecting what has the biggest impact on the user, because most people will not read it all. If they will only remember one thing, what is the one you want them to take away?
And as you said, often the spotlights are things that took just a few hours while the work that took the most efforts appears a small bullet point in the bottom.
Readit News
No, don't do this. Provide release notes, not release "announcements". Exhaustive is good; exhaustive is helpful to the reader. Let them know their "little" bug is fixed. Or maybe if you accidentally introduced a new bug with your change, or affected the user's workflow in some way, the reader can figure that out too.
The entire blog post is about how to corrupt release notes with marketing.
You don't have to sell your software to someone who is already using it. That's just annoying.
As an indie developer, my users say that they appreciate my exhaustive release notes.
I remember back when I worked for someone else, my boss always changed "fixed a crash" to "fixed a rare crash" in the release notes (whether or not that was accurate) LOL. Keep management and marketing away from the release notes if possible.
>> In contrast to release notes, which aim to be exhaustive, release announcements include only the most impactful changes.
>No, don't do this. Provide release notes, not release "announcements". Exhaustive is good; exhaustive is helpful to the reader. Let them know their "little" bug is fixed. Or maybe if you accidentally introduced a new bug with your change, or affected the user's workflow in some way, the reader can figure that out too.
They're not mutually exclusive. You can publish both release notes and a release announcement.
>You don't have to sell your software to someone who is already using it. That's just annoying.
I really disagree. I'm guessing you mean "sell" as in "manipulate" but I see it as "get users excited."
Of the software products I use and pay for, I appreciate it so much more when the vendor takes time to write a release announcement with care and focus on user needs. When I receive release announcements from Tailscale or Fly.io, I don't think, "Oh, boy, they're just trying to sell me something." I think it's cool that they're putting in the effort to showcase their work.
When vendors just publish a terse changelog, it feels like they don't care much about me and couldn't be bothered to present their work to me in a more accessible way.
Where, though? Consider the App Store, for example. You can have releases notes or a release announcement in the App Store along with a new version of your app, but not both.
The way you present it, with "good" vs. "bad", suggests that you're arguing for one, not for both, for release announcements instead of release notes.
> I'm guessing you mean "sell" as in "manipulate" but I see it as "get users excited."
But users don't need to get excited by every software update. That sounds like your need to get users excited about updates.
> When vendors just publish a terse changelog, it feels like they don't care much about me
That depends on what you mean by terse. "Bug fixes and performance improvements" is terse and careless. A comprehensive list of changes is not necessarily terse. And in a sense, "release announcements include only the most impactful changes" is terse too.
We have the concept of Release Announcements that are a quick attention grabber headline, followed on by Tasting Notes that explain in detail what changed and additional release notes.
That way the people who just want to understand the primary changes and those who want the details are happy.
I concur, please put all changes in release notes
Dead Comment
"Added 'duplicate' button to the event menu" is kind of exactly what I want to read.
I don't know -- maybe have both kinds? A simple, bare-bones set, and then an... "embellished" set?
Just a small title change would help a lot: "Create events 10x faster with new Duplicate button"
Thanks, that's a great suggestion! I've just updated the example.
Thanks for reading!
>To me, the examples in red are much more helpful -- they explain, in bare terms, what was actually done. The examples in green feel like a marketing exercise to me. Like they're trying to wrap or obscure clear writing in something to obfuscate it.
Oh, interesting. That surprises me. I think there are some cases where I want the short version (e.g., if I'm just looking for breaking changes or fixes to minor annoyances), but I generally think the release announcement does a better job at showcasing features.
Out of curiosity, do you find the example changelog-style announcement[0] more useful than the Figma's example release announcement[1]?
>I don't know -- maybe have both kinds?
Yes, absolutely. They're not mutually exclusive.
Whenever I've published a release announcement, I also link to a changelog, which is the bullet point list of changes. I think the changelog should also be more user-oriented than most currently are, but I think the changelog is the right place for an exhaustive list of anything that users might want to know about the new version.
[0] https://refactoringenglish.com/chapters/release-announcement...
[1] https://help.figma.com/hc/en-us/articles/23954856027159-Navi...
I'm all in skimming some bullet points on release notes but reading whole paragraphs for trivial announcements (like "Create events 10x faster") is an absolute no-go and wasted developer time in most cases.
"We sped up new file creation, so you can now create a new file in under 20ms, a 100x speedup from v1.2."
No. You had a big bug. You fixed it. Excellent. When I'm affected by the bug I'd search for "deadlock" or "bug " in the announcement and this is hiding it behind marketing speak. I don't think that's honest. So for me the perfect announcements would be the red ones.
>"We sped up new file creation, so you can now create a new file in under 20ms, a 100x speedup from v1.2."
>No. You had a big bug. You fixed it. Excellent. When I'm affected by the bug I'd search for "deadlock" or "bug " in the announcement and this is hiding it behind marketing speak. I don't think that's honest. So for me the perfect announcements would be the red ones.
I'm confused about how you'd know to search for those terms unless you were part of the dev team of that product.
A hang in the UI could just be the backend doing work in a way that's not optimized for UX. It's not necessarily a deadlock or a bug. Those are implementation details. It's not something a typical end-user can perceive just by using the software.
I think a release announcement is targeted at the same people who go to the marketing page for a product instead of the pricing and the docs.
One positive criticism: in my case (with a small user base of aprx 100), I feel it leans a bit too much into marketing. My users often want to know that a specific bug has been fixed. Release notes aren’t just about excitement, they’re also about trust and value.
Saying “Saving large files is now 10x faster” is great, but if users were dealing with crashes or freezes, it’s more helpful, and more direct, to combine your idea of clarity with the actual user experience:
“Saving large files is now 10x faster, no more freezes for files over 100MB.”
Being transparent about what was broken and now fixed is important.
Also, not sure if the article is focusing strictly on public-facing release announcements. I find it helpful to maintain a more detailed, separate internal changelog for future reference. That includes technical fixes, implementation notes, and lower-level changes that aren't relevant to users but are valuable to me.
That said, I mostly agree with your approach, and I think your method works really well for major or long-awaited feature releases.
Overall it's a good article and please take any of my feedback with a grain of salt, as my experience is mostly limited to a small user base and not large-scale or widely publicized launches.
Thanks for sharing!
>Saying “Saving large files is now 10x faster” is great, but if users were dealing with crashes or freezes, it’s more helpful, and more direct, to combine your idea of clarity with the actual user experience:
That's great feedback. I'd like to come up with a better example here.
I've noticed that when developers improve user experience, they tend to focus on what was bad rather than how it's now better, but I agree that the example is a bit confusing. If the fix is about a bug in a specific scenario, you do lose something in the announcement by not explaining how you fixed that particular bug.
> I thankfully avoided ever writing another uncomfortable explanation of a release that offers nothing to the user.
Seems short-sighted?
This is marketing-driven development where you have "learned the lesson" that thankless maintenance and stabilization tasks should be avoided.
Sometimes users just don't get it - and never will. Sometimes things are too technical to be useful to a user (the author touches on this themselves). Let the results speak for themselves - and be proud of your achievements, it sounds like this was a success.
Focussing too heavily on user facing issues is a kind of myopia that actually leads to a worse user experience over time, and, ironically, a slower turnaround for those user facing issues.
Considering the release announcement as part of sprint planning doesn't mean eliminating maintenance work. The release announcement is just the top N user-impacting changes in the release, so not every bit of dev work requires justification to the end-user.
The lesson I learned was that when I have a maintenance-heavy release, I needed to ensure that we have at least some work that's user-facing that we can present to users in the release announcement.
Every word is an opportunity for the reader to stop reading. Once they get a sense you're droning on, they'll stop.
To take the first example the author says needs fixing:
I think a better fix than the one in the article is: ```For reference here's the one from the article:
this little section gives me so much... dread.
on one hand, you have to be able to sell what you do; and on the other hand, if you cannot really quantify reasonable improvement to end user experience, can you really justify spending time on it?
we're basically back to figuring out how to allocate for "maintenace" that does not really translate to good "user story".
Yeah, this is something I struggled with as well. It didn't prevent me from allocating time to maintenance, but it meant I had to plan it more carefully. If I had a maintenance-heavy release, I made sure that we were including some "delighter" features even if they were small.
We often select 3 items and spotlight them in order of priority. So there is also an element of selecting what has the biggest impact on the user, because most people will not read it all. If they will only remember one thing, what is the one you want them to take away?
And as you said, often the spotlights are things that took just a few hours while the work that took the most efforts appears a small bullet point in the bottom.