Hacker News Board Hacker News, browsed like a classic message board
Live data from Hacker News

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

news.ycombinator.com

Post reply on HN
Print view View original

31–40 of 52 posts

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

#31

Post by bluenose69 »

I use a phone app called 'transit' to find out where the buses are at any moment. It's a great app for a lot of reasons, but the reason I was drawn to it at first was their witty release notes.

As the author of an R package, my release notes are much drier and businesslike. The package is quite static, so releases are mainly bug fixes. I start each item with either 'Add' or 'Change', then I name the function, and then I supply a short descriptive phrase and end with a link to the github issue where where users can see why the change was made, and what the code differences were.

I realize that this is not an answer to the question, really, because all users of the R package are basically on an even footing, in terms of knowing the R language and the science that the package is intended to support. If there is something transferrable to the OP's use-case, I guess it is to be systematic and terse, and to use a fairly fixed way of writing (being aware that not all users have English as the first language).

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

#32

Post by onion2k »

do you feel like more than one set is needed?

No. The release notes are for the end user.

There should be a separate changelog for technical users. This documents changes to the software including things that are invisible to users. For example, adding some unit tests wouldn't be in the release notes but it would be in the changelog.

Stakeholder comms is an entirely separate, but equally as important, thing. That should include information about impact the release is expected to have, what dependencies it impacts, and who gets the credit for work in the release.

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

#33

Post by Uvix »

Our release notes are all internal.

Each user story has separate fields with summary information, testing notes, and technical information for developers. The release process pulls the information from the linked user stories into an Excel spreadsheet, and the non-technical users just ignore that column.

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

#34

Post by captn3m0 »

This was a discussion point at the WriteTheDocs conference this year, and lots of teams were managing multiple release docs: changelog (mostly automated and granular), then release notes for notifying customers, followed by feature specific announcement blogs, which get condensed to the notification feature in the app itself.

One of the things that stood out was the need for the docs teams to have visibility and early notice about what is going into a release. Some teams mentioned using slack emojis for markers to help review what is proposed for promotion for eg. another was the buy-in to treat these various docs as strict release requirements (will you be willing to block a release because the docs aren’t ready?)

Lots of LLM-driven tooling attempts, but the Ghostty one is the only one I remember reading publicly.

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

#35

Post by AndrewDucker »

js4ever wrote: post #4

No one read them so a single version is more than enough

We read through the release notes for our server software before installing it so that we can warn users about new functionality, disable functionality that's not approved, etc.

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

#37

Post by spockz »

For us it is relatively straightforward. Every release gets one single post. It always gets a title highlighting the most important change highlighting why people want to upgrade. This is followed by a short summary of which usecase is now supported by a change we did (either added feature or some enhancement). This is again followed by a detailed story on the items above and finally a granular list of security, interface changes, etc., pointing at the relevant ticket number containing for each change the full reasoning and history.

Mostly this is a manual effort on the textual bit. A PR is required to indicate whether something is worthy to be specifically mentioned in the release notes. The list of concrete changes is automated.

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

#38

Post by catketch »

for me it has varied based on the product type and scope, i.e release note for everyone like on a mobile app release or a SaaS platform, vs a tenant specific customized release. There are multiple ways to single source it, and now LLMs can help you out a bit.

If you just need a simple thing, query what you are releasing (from jira or whatever tracking system you are using) and package them up into categories of features/bug fixes and keep the release notes general.

if it's important to have an accurate curated set of release notes, create a field in your bug db for external release notes---leave those for tehncical product managers, support etc to edit as they want. THen you can have internal and external ones.

you always need to review for language and sensitive data, so human review (but again LLMs are helpful now fo this stuff too)

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

#39

Post by maqnius »

A changelog.md file for users which is used to automatically create release messages.

If features need more explanation, we create a wiki page and link it in the release.

Sometimes we feel like there should be a changelog for devs but in the end git blame is used anyways.

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

#40

Post by wowczarek »

nofunsir wrote: post #26
joshgachnang wrote: post #22

Earlier quoted context omitted.

They're required for every version release and no one reads them anyway.

I read every single one. Any app that does this gets uninstalled and a nasty letter to software managers.

Well you're no fun, Sir...

While I'm morally tempted to do the same, many of the apps guilty of this are the major ones one uses, and as time goes by, I somehow find myself with less and less time on my hands, so I have to be selective with the things I want to do right and proper. Thus, by means of inaction, I indirectly contribute to the circle of enshittification, and there is no stopping it.

Post reply on HN