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.
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.
>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.
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.
Of course, if the statistic is actually core part of the product or a competitive differentiator, it should absolutely be highlighted.
"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 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.
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.
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’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.
"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.
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?
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.
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.
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:
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.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.
I concur, please put all changes in release notes
> 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.
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...
mtlynch•6h ago
MOARDONGZPLZ•5h ago
mtlynch•5h ago
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.
jeremy_k•4h ago
mtlynch•3h ago
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.