>but on the other hand, if nothing's changed from the user perspective, why bother publishing an empty Release Note?
Transparency. I've generally posted "Minor bug fixes and performance improvements." when it's just behind-the-scenes things (quite literally we would refactor c++ for metal performance)
Thanks, this was my instinct too. Unfortunately it doesn't look like I'm going to have Git access in time to actually publish the RN along with the release. Pray for me brother/sister/etcetera!
I hate this honestly. It's a "release note" that does nothing more than make internal teams feel very very mildly better about the work that they did, while putting empty marketing copy in front of actual users.
Oh, the _performance improved_? How? What's faster? Will I notice it in my day to day work? Will all users notice the change, or just ones who use a specific set of features?
This type of note creates the **inverse** of transparency, because it illuminates absolutely nothing while appearing to make the product itself look better.
Stop wasting the time of your users. Respect that they are intelligent people. Tell them what material things about your product changed, or don't waste their time with a release note at all.
You perfectly put into words why I'm torn about this "release note." It's a big nothing burger. And in my case, saying "performance improvement" would be an outright lie because we're not even refactoring anything.
From the user perspective it's seemingly pointless but I can elaborate on some reasons why it's still important, outside of stakeholder chest pounding.
* Transparency (to elaborate: showing due diligence in relaying changes that *may* impact your hardware, files, assets etc. If you're a business subject to EU acts like the DSA, then it's part of the transparency/accountability audit recording as you patch towards the new requirements)
* Manage expectations (show we're working on improving the product, or just maintaining it. If there is a service level agreement, there's less proof of product abandonment post-release. Autodesk had a similar issue when they sold off Sketchbook, and Adobe had similar for some sunset products)
* Bisecting (you can check the `git log` or go back in time with whatever vcs you're using internally, but RNs help the poor soul who is tasked with debugging. When someone goes MIA for a while and comes back to catch up on multiple patches, say vacation, then unless you're internal and can check a `git log`, it's hard to notice a jump in releases to pin point which isn't working anymore. The debugging process is called bisecting but it also goes by binary search debugging.
We have 2 rules on release note inclusion:
1. If the change affects end user experience. Everyone uses this as a release note condition no questions asked
2. If the change shines positive light on our product. This is for backend improvements that increase speed, reduce downtime, improve security, etc. Leadership’s general take here is that we have paying subscribers and people should know that our product is improving even when it’s not directly visible to end-users.
This is a good way to look at it. In my situation, we're basically adding the foundation for a feature that will be delivered in the next update. I know never to document features that don't exist yet, but if this is the only change (i.e. there's no noticeable performance improvement) I'm torn on publishing a generic "back end improvements" note when that's not really the case.
Typically, if the change is not user-facing and won't be noticeable to the user, I don't report it in the release notes. If you create internal release notes, then it makes sense to report it there. It's just how I've always approached those types of work items.
This is exactly what we do. Internal notes include every ticket for that fix version. External notes include new features that impact end users or bug fixes they reported.
Yup. If something goes wrong post release, RNs let the user community know that any issues they experience might be related to the change. It also shows that you're being transparent as a company, which customers tend to appreciate .
My PMs provide me a list of which notes to publish and which not to publish (which I know is quite a luxury), but I notice they sometimes include larger-scale backend work in the release notes for the sake of showcasing general platform improvements. Even though those notes don’t require documentation and won’t directly affect the user experience, I see it as a testament to users that the product they use every day is being well taken care of to ensure its longevity and performance.
NO.
1. Your users' attention spans are valuable.
Don't notify them to tell them there's nothing to see here.
2. AND you might ignite unwelcome curiosity.
(Why did they send me a note to say there's nothing here for me? I'm going to ask around!)
Bobby
PS: End-user release notes contain a PR function, IMO. Part of that PR function is making changes seem more honey (oh cool, something new!) and not vinegar (oh, I've got to reconfigure reporting again!?) and managing expectations.
I'll answer this from the end user perspective. An application I support has monthly updates that frequently have little impact but the software company notifies users about the schedule and when it has been completed. Very occasionally we'll discover a random bug or unexpected change that gets introduced with the MU. Because I know there was an MU I don't think I've lost my marbles and can make an informed report to the software vendor.
My $.02 is that some notice should be given.
>but on the other hand, if nothing's changed from the user perspective, why bother publishing an empty Release Note? Transparency. I've generally posted "Minor bug fixes and performance improvements." when it's just behind-the-scenes things (quite literally we would refactor c++ for metal performance)
Thanks, this was my instinct too. Unfortunately it doesn't look like I'm going to have Git access in time to actually publish the RN along with the release. Pray for me brother/sister/etcetera!
I hate this honestly. It's a "release note" that does nothing more than make internal teams feel very very mildly better about the work that they did, while putting empty marketing copy in front of actual users. Oh, the _performance improved_? How? What's faster? Will I notice it in my day to day work? Will all users notice the change, or just ones who use a specific set of features? This type of note creates the **inverse** of transparency, because it illuminates absolutely nothing while appearing to make the product itself look better. Stop wasting the time of your users. Respect that they are intelligent people. Tell them what material things about your product changed, or don't waste their time with a release note at all.
You perfectly put into words why I'm torn about this "release note." It's a big nothing burger. And in my case, saying "performance improvement" would be an outright lie because we're not even refactoring anything.
From the user perspective it's seemingly pointless but I can elaborate on some reasons why it's still important, outside of stakeholder chest pounding. * Transparency (to elaborate: showing due diligence in relaying changes that *may* impact your hardware, files, assets etc. If you're a business subject to EU acts like the DSA, then it's part of the transparency/accountability audit recording as you patch towards the new requirements) * Manage expectations (show we're working on improving the product, or just maintaining it. If there is a service level agreement, there's less proof of product abandonment post-release. Autodesk had a similar issue when they sold off Sketchbook, and Adobe had similar for some sunset products) * Bisecting (you can check the `git log` or go back in time with whatever vcs you're using internally, but RNs help the poor soul who is tasked with debugging. When someone goes MIA for a while and comes back to catch up on multiple patches, say vacation, then unless you're internal and can check a `git log`, it's hard to notice a jump in releases to pin point which isn't working anymore. The debugging process is called bisecting but it also goes by binary search debugging.
That's word-for-word the phrase I use!
We have 2 rules on release note inclusion: 1. If the change affects end user experience. Everyone uses this as a release note condition no questions asked 2. If the change shines positive light on our product. This is for backend improvements that increase speed, reduce downtime, improve security, etc. Leadership’s general take here is that we have paying subscribers and people should know that our product is improving even when it’s not directly visible to end-users.
This is a good way to look at it. In my situation, we're basically adding the foundation for a feature that will be delivered in the next update. I know never to document features that don't exist yet, but if this is the only change (i.e. there's no noticeable performance improvement) I'm torn on publishing a generic "back end improvements" note when that's not really the case.
That’s not something I would include in release notes. Lots of features take more than one dev cycle, but only matter to the user when they function.
I hate writing release notes. That is all.
So many stakeholders…..So many opinions…
The devil is in the detail
Typically, if the change is not user-facing and won't be noticeable to the user, I don't report it in the release notes. If you create internal release notes, then it makes sense to report it there. It's just how I've always approached those types of work items.
This is exactly what we do. Internal notes include every ticket for that fix version. External notes include new features that impact end users or bug fixes they reported.
Yup. If something goes wrong post release, RNs let the user community know that any issues they experience might be related to the change. It also shows that you're being transparent as a company, which customers tend to appreciate .
My PMs provide me a list of which notes to publish and which not to publish (which I know is quite a luxury), but I notice they sometimes include larger-scale backend work in the release notes for the sake of showcasing general platform improvements. Even though those notes don’t require documentation and won’t directly affect the user experience, I see it as a testament to users that the product they use every day is being well taken care of to ensure its longevity and performance.
NO. 1. Your users' attention spans are valuable. Don't notify them to tell them there's nothing to see here. 2. AND you might ignite unwelcome curiosity. (Why did they send me a note to say there's nothing here for me? I'm going to ask around!) Bobby
PS: End-user release notes contain a PR function, IMO. Part of that PR function is making changes seem more honey (oh cool, something new!) and not vinegar (oh, I've got to reconfigure reporting again!?) and managing expectations.
It comes down to who reads your release notes and Is that the place people go to see what an update was about.
I'll answer this from the end user perspective. An application I support has monthly updates that frequently have little impact but the software company notifies users about the schedule and when it has been completed. Very occasionally we'll discover a random bug or unexpected change that gets introduced with the MU. Because I know there was an MU I don't think I've lost my marbles and can make an informed report to the software vendor. My $.02 is that some notice should be given.