Live data from Hacker News

Ask HN: How do you handle release notes for multiple audiences?

news.ycombinator.com

1–10 of 52 posts

Ask HN: How do you handle release notes for multiple audiences?

#1
For those of you who ship often, when you release updates, do you typically write one set of release notes, or do you end up rewriting them for different audiences?

For example: • technical version for developers • simplified version for end users • something more high-level for stakeholders etc…

In my current position I’ve seen a plethora of different ways teams, and even the company I currently work for, go about this.

What I’ve seen: 1. paste raw GitHub changelogs into customer emails (highly wouldn’t recommend if you’re currently doing this ) 2. manually rewrite the same update multiple times for each audience 3. skip release notes entirely because it’s too much work

So I guess my question is: How do you or your company currently go about handling more than one set of release notes, and do you feel like more than one set is needed?

Would love to hear what’s working (or not working) for you, and if you found any tools that help mitigate this issue.

Re: Ask HN: How do you handle release notes for multiple audiences?

#3
post #2

I automate one changelog per project using git-cliff and conventional commits: https://github.com/orhun/git-cliff https://www.conventionalcommits.org/en/v1.0.0/ This changelog is copied into the release on github, or wherever the release is announced.

really helpful, thanks for sharing!

Re: Ask HN: How do you handle release notes for multiple audiences?

#6
If there is an audience for release notes I haven't seen anything better than just committing entries to a pre-release folder as you change things and have release automation compile the folder into the actual release notes. Python and many other large projects handle it like this: https://github.com/python/cpython/tree/main/Misc/NEWS.d/next (The release notes for major releases are crafted manually)

On the other hand, for many projects you can probably skip release notes: nobody will read them. Even fewer people would read automatically generated changelogs: don't bother setting it up. Releasing instead of deploying from master also implies you took more care than usual, did you? Commit messages make sense for cohesive changes, are they? Didn't think so.

Re: Ask HN: How do you handle release notes for multiple audiences?

#9
I think a lot of it boils down to your goals with it, I'm personally very engaged with my user base and take pride in my communication and you may not value that over less work/more dev time. This is also for an internal tool but the audience is diverse (500+ devs, cybersecurity engineers, leadership, writers, etc), I stick with one set of release notes for a few reasons:

- One location, people who may fall into multiple categories (or none) don't need to check multiple places, users also know that all my communication will be via that page/they don't have to wonder if they're missing something

- As much as some detail doesn't matter to certain audiences, I find being able to give all the detail you want a user to know while maintaining readability to less technical audiences is a skill worth developing because the result is regardless of where your notes end up, the person will understand what's changed and why it matters

- Maintaining multiple versions leads to mistakes, at some point you'll leave out a detail to one audience that matters so letting the user mentally filter what they don't care about takes the onus to get it right 100% of the time off of you. I'll often categorize my changes by the section that had the change to help users with this.

- This is a personal preference and you touched on this one but it's just far less work, I've found it common in tech that people don't want to do things more than once or they'll automate it/look for shortcuts and this is no different. This isn't always a bad thing but getting release notes right means your users stay informed/use new features which is why we build them so I think it's worth putting my energy into doing it properly every time

Re: Ask HN: How do you handle release notes for multiple audiences?

#10
post #7

As per industry standards: v1.4.18 - "Bug fixes and performance improvements" v1.4.17 - "Bug fixes and performance improvements" v1.4.16 - "Bug fixes and performance improvements"

Yeah that pretty much describes every big companies release notes. I used to have manual updates in the Google Play store as I enjoyed seeing what was changing. But over time so many companies just started saying things like "Security fixes" and it became a waste of time even bothering to look at them.

And sometimes they do actually add a feature... but they'll mention it within the app itself despite the app updates not mentioning it. Or even more funny is how often I'll see a news article talking about the new feature, but then it never even gets mentioned in the release notes anywhere.

Post reply on HN