Live data from Hacker News

Lets talk about changelogs (how I loathe 'bugfixes and performance improvements)

raymii.org

91–100 of 127 posts

Re: Lets talk about changelogs (how I loathe 'bugfixes and performance improvements)

#91

With many apps an issue for changelog writers is that often behavior is tied to feature flags, which can be remotely enabled. Thus a new feature is rolled out in the app but only visible to some testers. Only after a while it's enabled for all users. Thus app release is independent from availability of a feature. That said "Bugfixes and performance improvements" is as useless as it gets ...

I wonder how those features pass Apple review? It's easy to disable those flags to get review passed and enable them later.

It depends on the feature. For things that involve material changes to your app or a feature that you don't want Apple to be surprised about, usually you will include user credentials in your submission that have that feature enabled and give them a heads up. If's a smallish feature, you don't usually sweat app review. It's obviously not a perfect system.

Re: Lets talk about changelogs (how I loathe 'bugfixes and performance improvements)

#92
post #66

The problem is often the "bugfixes and performance improvements" are a list of 60 things, and for almost all users "there are less crashes and it is faster" is all they would want to know. How many users want to read (OK, possibly people here) "On some versions of glibc, the 32-bit specialisation of memcpy which used SSE2 instructions had a bug when the memory being copied crossed the 2GB boundary, so in that case we…

I think the author of the article brings up a good point regarding this, though. If you're a non-technical user, you're not going to read it at all. You might update, you might not, but you're not going to look through the list of changes. If you're a technical user, you know it's unlikely that update == "more crashes and slower load times" so saying the opposite isn't helpful, and a list of things might be helpful.…

I tend to fall in either 1 or 2 depending on whether I've been bitten by a specific bug and need to know if it has been fixed.

The worst changelogs are the ones that say "Performance improvements and bugfixes" only to find out the entire user interface has changed after updating.

Re: Lets talk about changelogs (how I loathe 'bugfixes and performance improvements)

#93
How much value does the average user get out of better patch notes? None, since they don’t even read the patch notes. So is that worth the time for each issue to write and edit a user-facing piece of documentation?

Every little task like this is a waste of time and mental energy that slows down useful work. In my opinion, this is just not worth the effort.

Re: Lets talk about changelogs (how I loathe 'bugfixes and performance improvements)

#94
post #80
post #14

Earlier quoted context omitted.

> The article says at the end: "You see? Not that hard right?". It is that hard in bigger organisations. The size of the organisations is not important, as is the size of the team working on the particular feature/app. Apple is huge, for example, but eg. Logic Pro has great changelogs. We also see huge apps (with large teams) do better than than small apps (with much smaller teams). It's more about bothering/caring t…

Logic Pro doesn't have server-side feature flags.

Many apps don't have either, and they have shitty changelogs still...

Re: Lets talk about changelogs (how I loathe 'bugfixes and performance improvements)

#96
post #94
post #80

Earlier quoted context omitted.

Logic Pro doesn't have server-side feature flags.

Many apps don't have either, and they have shitty changelogs still...

As far as I know all the big apps the OP is complaining about have server-side feature flags.

Re: Lets talk about changelogs (how I loathe 'bugfixes and performance improvements)

#97
post #85
post #79

Earlier quoted context omitted.

Assuming there are good rollout and incident review processes in place, this isn't much of a problem in practice.

If you're shipping a mobile app with client side code (so, nearly all of them), there is no good rollout process. You can't ship a quick update with Apple, because review isn't quick. Users who upgraded soon after release will be stuck with something broken until the new version is available. You can usually ship quickly with Google, but users are slow to upgrade, but may have caught your first one, and not get your…

I'm talking about feature flag based rollouts, which don't involve going through Apple or Google.

Re: Lets talk about changelogs (how I loathe 'bugfixes and performance improvements)

#98

How much value does the average user get out of better patch notes? None, since they don’t even read the patch notes. So is that worth the time for each issue to write and edit a user-facing piece of documentation? Every little task like this is a waste of time and mental energy that slows down useful work. In my opinion, this is just not worth the effort.

I too basically disagree with the author (for reasons I'll go into below), but I think it's worth unpacking a little further that high quality release notes can form an important part of your communication strategy with your users. Note: high quality.

Many years ago I worked for a tools company where, for our less popular tools, user count would be in the thousands to tens of thousands, and for the more popular tools, it would be in the hundreds of thousands. Every single time we put out a release you could guarantee that a handful of people would ask for release notes even though we'd always publish them. Clearly people wanted them.

Now I work for a company where our platform caters to two very distinct groups of users - one group internal, the other external. Particularly for the internal users release notes are hugely important in order to avoid disrupting their work and deliverables to customers.

In both companies we've often had an "additional bug-fixes and performance improvements" item in the list.

Why?

Because people only have so much attention to go around: they're busy and, particularly in my current role and with our internal users, it's critical that we draw that limited supply of attention toward the most important changes. That's much more valuable than sending out an exhaustive document of every single change every time we do a release. We've found that if we supply exhaustive notes, fewer people tend to read them, and we get complaints that they're too long. As you've already suggested it comes down to ensuring that the release notes you provide are actually valuable to users.

Together with other documentation and training materials, release notes can provide a useful jumping off point for learning how to work with changes and improvements to our software.

(Not everybody reads them, of course, but having them does at least mean that when they inevitably ask for help/information, we can point them at the release notes as a starting point.)

Re: Lets talk about changelogs (how I loathe 'bugfixes and performance improvements)

#99

The problem is often the "bugfixes and performance improvements" are a list of 60 things, and for almost all users "there are less crashes and it is faster" is all they would want to know. How many users want to read (OK, possibly people here) "On some versions of glibc, the 32-bit specialisation of memcpy which used SSE2 instructions had a bug when the memory being copied crossed the 2GB boundary, so in that case we…

There’s also a mitigating liability aspect to this. If you start providing minutiae detail, you may start revealing pretty big faults that have escaped to prod. People question the safety of your product and now you’re open to lawsuit or at least micromanaged by some unforgiving end-customers. To cope, you start to not fix certain problems so you won’t have to report the bugs or you start lying what the bugs were. I’…

Back in the 80s when I was starting out in the compiler business, I thought it would be a good service to include with it a list of the known bugs.

It didn't take long before a magazine reviewer did a compiler roundup and simply printed the bug list as his "review". It was a disaster for my business.

It took me 20 years to get over being brutalized by that and make the bug list publicly available again.

https://issues.dlang.org/

Re: Lets talk about changelogs (how I loathe 'bugfixes and performance improvements)

#100
post #60

The problem is often the "bugfixes and performance improvements" are a list of 60 things, and for almost all users "there are less crashes and it is faster" is all they would want to know. How many users want to read (OK, possibly people here) "On some versions of glibc, the 32-bit specialisation of memcpy which used SSE2 instructions had a bug when the memory being copied crossed the 2GB boundary, so in that case we…

I think the key is describing the user-facing effects and impact. This means knowing your users (are they developers, IT or highly technical? Do they automatically or manually update quickly, or do they take time to evaluate before rolling out updates?). It's a way to convey continuing value to users and convince them it's worthwhile to keep paying, and get motivated to get the update. I'd try to change what you wrot…

> Doing this well takes time

For us, not that much time, as everything goes through the bug tracker (even enhancements) so it's mostly a copy-pasta job. When I submit a fix for a bug, I'll often edit the subject to accurately reflect what the problem actually turned out to be.

Post reply on HN