5 ms·

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

by lapcat 1y ago

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

cthor 1y ago
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.
- pinoy420 1y ago
  [dead]
mtlynch 1y ago
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.
- lapcat 1y ago
  > 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.
  - mtlynch 1y ago
    > 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 https://keepass.info/news/n250304_2.58.html [1] https://keepass.info/news/n240601_2.57.html https://keepass.info/news/n240601_2.57.html
bravesoul2 1y ago
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.
lovich 1y ago
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

by lapcat 1y ago

cthor 1y ago

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.

pinoy420 1y ago
[dead]

mtlynch 1y ago

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.

lapcat 1y ago
> 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.
- mtlynch 1y ago
  > 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 https://keepass.info/news/n250304_2.58.html [1] https://keepass.info/news/n240601_2.57.html https://keepass.info/news/n240601_2.57.html

bravesoul2 1y ago

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.

lovich 1y ago

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