How to Write Compelling Release Announcements

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.

"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?

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!

> 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.

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.

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".

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.

> 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.

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.

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...

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.