How to Write Compelling Release Announcements

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?

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.

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

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

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.

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.

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.

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"

Thanks, that's a great suggestion! I've just updated the example.

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?

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”

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.