Ask HN: If you write release notes, what stops you from being specific?

3 points by gtirloni 43 days ago | 4 comments

Slack's release notes (https://slack.com/release-notes) are mostly "Bug fixes and performance improvements." or something trying too hard to be funny.

If you write release notes for software with a lot of users: what makes you go generic? I assume there's a reason past laziness and I'd rather hear it from someone who's made the call.

Bsierakowski1 29 days ago |

I've been building a product in the release notes space, I think the issue is that the act of writing good release notes is so far removed from the benefits of writing great release notes that companies have a hard time justifying the effort.

I'm totally convinced good product comms gets you more customers and keeps them longer, but it's hard to see the direct impact, and it's actually kinda hard to do product updates well.

I could see this changing over the next many months / years as more people turn to AI to recommend products, it's true that most users dont read through your changelog, but the AIs will, and the more functionality you share with the AI the better it'll do of "selling" for you.

Jemaclus 42 days ago |

I guess I'd turn the question around to you: what do you want to see in release notes that you don't already see? What information do you feel is missing?

From my personal experience, the context of the fix lives in a dozen different places: the ticket, the code, the commit message. And now I need to document it a fourth time? From a dev perspective, the value just isn't there beyond a vague "fixed zoom issue for #1355," because you can go look at ticket 1355 and see the context, and look at the diff to see what changed.

From a dev's perspective, I'm documenting the same thing for the fourth time, except this time, perhaps, I have to think about the information from the perspective of a customer or non-technical person, and then decide how much information and detail is appropriate, and so on and so forth. I wouldn't say it's laziness, per se, as much as it's more work, and we have a lot of other things to do.

Also, let's be real: how many people read release notes? My boss doesn't, the CEO doesn't. Release note quality doesn't show up on my performance reviews. Customers don't leave Yelp reviews or App Store reviews because my release notes were bland. There's no career incentive for me to do "better." Maybe that should change, but that's the reality.

So the question comes back to you: what value are you seeking from release notes, and what level of detail makes sense to you?

gtirloni 41 days ago | |

That's a very long comment to say "nobody reads docs". Also, you're asking me to explain the value of release notes to you in particular.

gus_massa 41 days ago |

From my experience in Racket, some bug fixes are weird corner cases that need a lot of explanation to understand the problem and how it was fixed.