How to Write Compelling Release Announcements(refactoringenglish.com)
refactoringenglish.com
How to Write Compelling Release Announcements
https://refactoringenglish.com/chapters/release-announcements/
17 comments
Thanks for reading, Jeff!
>> 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.
>> 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.
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 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 don't think release notes are bad, but I think adopting a release notes style for a release announcement is bad. Similarly, I think adopting a commit message style in release notes is bad.
I'll look for ways to clarify this in the article.
>> 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.
When I say "terse" I mean that they describe each individual change tersely. KeePass is an example of a vendor I think publishes release announcements with terse change rundowns, and I think the announcements suffer because of it.[0, 1] When minor changes get the same screen real estate as big new features, it's hard for the reader to recognize the important features because the signal to noise is too high.
Out of curiosity, what's your opinion of KeePass release announcements?
[0] https://keepass.info/news/n250304_2.58.html
[1] https://keepass.info/news/n240601_2.57.html
I don't think release notes are bad, but I think adopting a release notes style for a release announcement is bad. Similarly, I think adopting a commit message style in release notes is bad.
I'll look for ways to clarify this in the article.
>> 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.
When I say "terse" I mean that they describe each individual change tersely. KeePass is an example of a vendor I think publishes release announcements with terse change rundowns, and I think the announcements suffer because of it.[0, 1] When minor changes get the same screen real estate as big new features, it's hard for the reader to recognize the important features because the signal to noise is too high.
Out of curiosity, what's your opinion of KeePass release announcements?
[0] https://keepass.info/news/n250304_2.58.html
[1] https://keepass.info/news/n240601_2.57.html
KeePass is a free open source project.
>KeePass is a free open source project.
Can you state your point more explicitly? That fact seems unrelated to my question.
Can you state your point more explicitly? That fact seems unrelated to my question.
My point is that I would give them a break.
And if the purpose of your blog post were to lecture free open projects, that would make it even worse, indeed repulsive, frankly.
And if the purpose of your blog post were to lecture free open projects, that would make it even worse, indeed repulsive, frankly.
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.
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”
I concur, please put all changes in release notes
I concur, please put all changes in release notes
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?
"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 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”
>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, that's a great suggestion! I've just updated the example.
Author here.
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...
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...
> 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.
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.
When I read that, I feel like I am being sold to and I need to decode it to find out what the actual change is.
I’m generally in agreement that you should write release announcements in terms that relate to what the end-user is trying to accomplish and not just a mechanical diff, but this goes approximately 100% too far.
I’m generally in agreement that you should write release announcements in terms that relate to what the end-user is trying to accomplish and not just a mechanical diff, but this goes approximately 100% too far.
I notice that you said "wasted developer time" rather than "user time" so maybe this is the difference?
I think too many developers write about their software as if the readers are other developers, especially developers with high context into the software. But for most software, the users are not developers, and they generally have much less context than the developers working on it.
I can understand how "Add a duplicate event button" is sufficient if I'm communicating with another developer on an open-source project, but I think the typical end-user requires more explanation of why that button is useful and what they can do with it.
I think too many developers write about their software as if the readers are other developers, especially developers with high context into the software. But for most software, the users are not developers, and they generally have much less context than the developers working on it.
I can understand how "Add a duplicate event button" is sufficient if I'm communicating with another developer on an open-source project, but I think the typical end-user requires more explanation of why that button is useful and what they can do with it.
> I notice that you said "wasted developer time" rather than "user time" so maybe this is the difference?
Maybe both? It's wasted developer time because someone has to curate the list and write it up for an audience that does not exist or is equivalent to your own marketing and sales department?
Maybe both? It's wasted developer time because someone has to curate the list and write it up for an audience that does not exist or is equivalent to your own marketing and sales department?
You don't have to ramp up marketing to 11 to write release notes that users can understand. Those are users of software that they already have and use. They will know what the changes mean for them.
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.
Thanks for reading!
>"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.
>"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.
While you have a point for "deadlock", I'd say "bug" as a generic term for a software fault is fairly pervasive outside of the tech industry.
That said, there's an even better word IMO: "fix"
The wording you used for the new file speed-up feels like you're talking about a feature. The way it is worded you can technically read as a fix or a feature, but the way it's expressed feels like something greater than a bug fix occurred. As an end user, I would be wondering if I was going to experience a completely different flow to create a new file because that whole part of the software has been redone or something.
If it were up to me to write that entry on a release announcement, I'd probably say something like: "We fixed an issue that could cause a long delay when creating a new file."
Which is pretty close to your boring/dev-focused version, mostly dropping a few technical terms like "deadlock" and "UI". Calling it a fix makes it clear this isn't new functionality. If I am a user who has been tripping over this bug a lot, I'll recognize the description of the impact because it aligns to my experience of the product.
I don't need to come up with a contrived metric like "100x speedup". Is that even accurate for the situation being described, outside of edge cases? The boring version:
"Fixed a thread deadlock that froze the UI for up to two second when creating a new file."
From that, I take the implication that the problem does not necessarily happen every time a new file is created, and when it does, it does not necessarily take the full 2 seconds. That's being described as the worst-case scenario. For the average end user, are they going to actually experience a 100x speedup? Or are they going to create a new file and notice effectively nothing different, and wonder what the hell you're talking about?
That said, there's an even better word IMO: "fix"
The wording you used for the new file speed-up feels like you're talking about a feature. The way it is worded you can technically read as a fix or a feature, but the way it's expressed feels like something greater than a bug fix occurred. As an end user, I would be wondering if I was going to experience a completely different flow to create a new file because that whole part of the software has been redone or something.
If it were up to me to write that entry on a release announcement, I'd probably say something like: "We fixed an issue that could cause a long delay when creating a new file."
Which is pretty close to your boring/dev-focused version, mostly dropping a few technical terms like "deadlock" and "UI". Calling it a fix makes it clear this isn't new functionality. If I am a user who has been tripping over this bug a lot, I'll recognize the description of the impact because it aligns to my experience of the product.
I don't need to come up with a contrived metric like "100x speedup". Is that even accurate for the situation being described, outside of edge cases? The boring version:
"Fixed a thread deadlock that froze the UI for up to two second when creating a new file."
From that, I take the implication that the problem does not necessarily happen every time a new file is created, and when it does, it does not necessarily take the full 2 seconds. That's being described as the worst-case scenario. For the average end user, are they going to actually experience a 100x speedup? Or are they going to create a new file and notice effectively nothing different, and wonder what the hell you're talking about?
They note that you should have both release notes and a release announcement.
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.
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.
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.
Thanks for sharing!
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!
Thanks for reading!
>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.
>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 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.
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.
Author here. Thanks for reading!
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.
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:
For reference here's the one from the article:
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.
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".
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".
Thanks for reading!
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.
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.
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.
The advice is all good. For the specific examples, claims with a lot of concrete numbers should be handled carefully. Unsophisticated users can bounce off numbers rather than content. Sophisticated users might care about the numbers, but are able to recognize spin - 200x speedups are clearly a bugfix rather than an innovative new algorithm.
Of course, if the statistic is actually core part of the product or a competitive differentiator, it should absolutely be highlighted.
Of course, if the statistic is actually core part of the product or a competitive differentiator, it should absolutely be highlighted.
I am curious about this:
> I awkwardly tried to explain to our users why we made them wait five months for a release that essentially did nothing for them.
Are the users waiting? Most of the time when using software I am not waiting for new features. I am happy if you keep it stable and working. Unless there is a real pain point in some process (e.g. something very manual that you should automate).
I think it is OK to have releases with no new features.
> I awkwardly tried to explain to our users why we made them wait five months for a release that essentially did nothing for them.
Are the users waiting? Most of the time when using software I am not waiting for new features. I am happy if you keep it stable and working. Unless there is a real pain point in some process (e.g. something very manual that you should automate).
I think it is OK to have releases with no new features.
Updates as marketing? Makes sense, but not well-executed by OP.
The update titles are good, but try focusing on the feature, not the “toil.” If I’m using your product and want the feature, you’re telling me what I already know. Keep text to a minimum.
Revised first example (duplicate button):
You can now create repeating events by clicking “Options > Repeat.” Sync with company holiday schedule to skip repeat events on holidays.
The update titles are good, but try focusing on the feature, not the “toil.” If I’m using your product and want the feature, you’re telling me what I already know. Keep text to a minimum.
Revised first example (duplicate button):
You can now create repeating events by clicking “Options > Repeat.” Sync with company holiday schedule to skip repeat events on holidays.
I generally agree with these points but I sometimes find "do X, not Y" suggestions too prescriptive to be helpful. Compelling phrasing should be context-aware and mindful of how users actually use the product, what their pain points are, and what they find useful.
Largely I take issue with the use of metrics. "Create events 10x faster" reminds me of the "put hard numbers in your resume" advice that people blindly follow — it's not a useful description to use here! When I go into XYZ Calendar and create a new event by copy-pasting fields, I don't think "hey I wish this was 10x faster" but rather "I wish I didn't have to do this". Announcing the feature as "Duplicate events instantly" cuts right to the heart of the improvement without splitting hairs of "I can do unnecessary work N times faster".
For "fixed a thread deadlock that froze the UI for up to two second when creating a new file" vs. "we sped up new file creation, so you can now create a new file in under 20ms, a 100x speedup from v1.2" — if the new file stutter is a common complaint, we can celebrate this by acknowledging the flaw and its fix. "Creating a new file is now instant after we fixed a thread deadlock bug" conveys that (1) a common user annoyance is now gone, (2) we recognized that it was an annoying bug, and (3) we put in the work to fix it. And no "100x" in there — we didn't speed up an annoyance, we got rid of it entirely.
Of course performance metrics aren't always bad — "Gleam JavaScript gets 30% faster" announcement is great! But compiled language speedups is something that users care about, and not something we want to abstract away (e.g. by merely saying "faster" or "better"). Here, putting a concrete number in the title and letting it speak for itself is absolutely the right choice.
Context is everything for making writing compelling. On that note — Style: Towards Clarity and Grace [0] is the best book I have read on writing clearly and effectively.
[0] https://en.m.wikipedia.org/wiki/Style:_Lessons_in_Clarity_an...
Largely I take issue with the use of metrics. "Create events 10x faster" reminds me of the "put hard numbers in your resume" advice that people blindly follow — it's not a useful description to use here! When I go into XYZ Calendar and create a new event by copy-pasting fields, I don't think "hey I wish this was 10x faster" but rather "I wish I didn't have to do this". Announcing the feature as "Duplicate events instantly" cuts right to the heart of the improvement without splitting hairs of "I can do unnecessary work N times faster".
For "fixed a thread deadlock that froze the UI for up to two second when creating a new file" vs. "we sped up new file creation, so you can now create a new file in under 20ms, a 100x speedup from v1.2" — if the new file stutter is a common complaint, we can celebrate this by acknowledging the flaw and its fix. "Creating a new file is now instant after we fixed a thread deadlock bug" conveys that (1) a common user annoyance is now gone, (2) we recognized that it was an annoying bug, and (3) we put in the work to fix it. And no "100x" in there — we didn't speed up an annoyance, we got rid of it entirely.
Of course performance metrics aren't always bad — "Gleam JavaScript gets 30% faster" announcement is great! But compiled language speedups is something that users care about, and not something we want to abstract away (e.g. by merely saying "faster" or "better"). Here, putting a concrete number in the title and letting it speak for itself is absolutely the right choice.
Context is everything for making writing compelling. On that note — Style: Towards Clarity and Grace [0] is the best book I have read on writing clearly and effectively.
[0] https://en.m.wikipedia.org/wiki/Style:_Lessons_in_Clarity_an...
This is good. I realized last year that every time I release a new version of my software is a chance for people who have never heard of that software to get their first exposure to it.
As such, I've tried to put more effort into my release notes - based on the idea that some of the people who read them may not have experienced the software before.
I had not considered the difference between release notes and a release announcement as described here. I will be thinking about that in the future.
As such, I've tried to put more effort into my release notes - based on the idea that some of the people who read them may not have experienced the software before.
I had not considered the difference between release notes and a release announcement as described here. I will be thinking about that in the future.
Thanks for reading, Simon!
>I've tried to put more effort into my release notes - based on the idea that some of the people who read them may not have experienced the software before.
That's something I try to be mindful of as well. If I think someone might discover a release announcement that isn't already a user, I want it to be easy for them to understand what the software does at all.
I see so many posts reach the front page of HN that are like, "OpenVQ7 reaches 1.0 release" and the post never explains what the heck OpenVQ7 is at all. And I always feel like, "Just add one sentence explaining what this is." You're not going to alienate your existing users with a one-sentence explanation, even if it's something they already know.
>I've tried to put more effort into my release notes - based on the idea that some of the people who read them may not have experienced the software before.
That's something I try to be mindful of as well. If I think someone might discover a release announcement that isn't already a user, I want it to be easy for them to understand what the software does at all.
I see so many posts reach the front page of HN that are like, "OpenVQ7 reaches 1.0 release" and the post never explains what the heck OpenVQ7 is at all. And I always feel like, "Just add one sentence explaining what this is." You're not going to alienate your existing users with a one-sentence explanation, even if it's something they already know.
Thank goodness I don't have to do “release announcements”. The provided examples all look horrible to me. Release notes are perfectly fine, with 0% of irrelevant fluff.
Also: Please don't announce it as "Thingie 3.5.27". That title says nothing about what's new or interesting about this release.
It actually does, specifically it indicates the degree to which something has changed - importantly, if action is required on the user's end (breaking releases). Or if there have been significant changes or a milestone was released (e.g. 1.0.0 means it's stable for production)
As a developer I can tell at a glance how much work this will take and whether to escalate it.
That being said I'm not opposed to a bit more detail "Thingy 3.12.10 - Miraculous Monitoring Metrics". And also I don't see a point in non-technically focussed products using this style either.
https://semver.org/
As a developer I can tell at a glance how much work this will take and whether to escalate it.
That being said I'm not opposed to a bit more detail "Thingy 3.12.10 - Miraculous Monitoring Metrics". And also I don't see a point in non-technically focussed products using this style either.
https://semver.org/
Author here. Happy to take any feedback or questions about this post.
Working at a company that has a structure for our product announcements that falls in line with this article, everything you said resonated. It is very interesting to come to the comments and see some negative feeling towards writing that is focused on the end user. I mean I get it, HN has a heavy user base of software engineers and so there is likely bias in what a software engineer wants to read vs the typical end user. It seems there may be value in product announcement geared towards end users and a release notes geared towards developers.
Thanks for reading and for the kind words!
I know a lot of the comments are critical, but I find the feedback helpful, and I've already made some improvements to the article based on the comments here. In some cases, I think there's pure disagreement, where some commenters feel that anything other than a dev-oriented changelog is "selling out" to marketing. Some of the feedback is misunderstanding what I'm advocating (e.g., some readers perceived the post as advocating release announcements instead of changelogs). But in the end, my audience for this post is developers, so it's helpful to hear candid reactions from developers, even though I know HN commenters aren't perfectly representative of developers in general.
I know a lot of the comments are critical, but I find the feedback helpful, and I've already made some improvements to the article based on the comments here. In some cases, I think there's pure disagreement, where some commenters feel that anything other than a dev-oriented changelog is "selling out" to marketing. Some of the feedback is misunderstanding what I'm advocating (e.g., some readers perceived the post as advocating release announcements instead of changelogs). But in the end, my audience for this post is developers, so it's helpful to hear candid reactions from developers, even though I know HN commenters aren't perfectly representative of developers in general.
I read the whole thing and didn't know what a release announcement was until the section where you pointed to "real world examples," which linked to elsewhere. I did pick up from your text that they are not the same as release notes though. Could I suggest you succinctly define what you consider to be a release announcement at the outset?
Thanks for reading! That's great feedback.
Do you feel like this would be a helpful definition to include at the top?
>A release announcement is a summary of the changes that will have the greatest impact on the user's experience. It presents them in a clear, accessible way that focuses on the user.
Do you feel like this would be a helpful definition to include at the top?
>A release announcement is a summary of the changes that will have the greatest impact on the user's experience. It presents them in a clear, accessible way that focuses on the user.
[deleted]
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.