Nobody Reads the Changelog

I write release notes for every version of Broadcast. I put real effort into them. And I have made peace with the fact that most people, most of the time, do not read them — because I don’t read yours either.

For hosted software this is a solvable problem: the vendor knows when you last logged in, ships an in-app announcement, emails your account. Self-hosted is harder in an interesting way. You control when you upgrade. You might jump three versions at once. The features you paid for arrive silently, live in a part of the app you don’t visit, and sit there unfound until you happen to click the right menu.

I’d shipped things — good things — that customers later asked me to build. That’s the failure this release is about.

A tour, after the upgrade, once

Version 2.15 adds a What’s New tour. Upgrade, log in, and you get a short walkthrough of what’s changed since your last version.

Each slide is one feature: a screenshot of the actual screen, two or three sentences on what it does, and a button that takes you straight there. Not a wall of bullet points — the thing itself, and a door to it.

Three constraints shaped it, and they’re all about not being obnoxious:

It appears once per user. Not once per install, per user — because on a team of five, four people shouldn’t have their day interrupted by a tour the admin already dismissed on everyone’s behalf. And once means once. It does not come back next week to check whether you’ve reconsidered.

It’s dismissible at any time. Close it on slide one and it’s gone. There is no “are you sure?”, no re-prompt, no clever second attempt. If you don’t want the tour, you don’t want the tour.

It covers the gap you actually crossed. Skip from 2.13 to 2.17 and you get the features from all four releases, not just the newest one. Upgrading late shouldn’t mean the middle versions never get introduced.

Why a screenshot per slide matters more than the text

The first version I sketched was text-only, and it was useless. “Segments now support relative dates” means nothing until you have seen the rule builder with a days ago selector sitting in it. The screenshot does the explaining; the words just add the reasoning.

That has a cost on my side — it means every release now involves capturing real screenshots of the new screens, from a real browser, against real-looking data. That work is automated in the app’s own test suite, which drives a browser through the new features and saves the images. Feature work isn’t finished until the pictures exist.

Which, honestly, is a healthy forcing function. If a feature is hard to screenshot in a way that makes sense to someone who has never seen it, that is usually the feature telling you something.

What this looks like from your side

You upgrade quarterly. You come back to a tour of everything in the gap, click through five slides in ninety seconds, and land on the two screens worth your time. Compare with reading four sets of release notes, which is to say: not doing it.

You run a team. Your colleague who only writes broadcasts gets the tour on their next login, on their own schedule, and finds the two features relevant to their job without you having to run an internal announcement.

You don’t care today. You close it. That’s it — that’s the whole interaction.

The rest of 2.15

Broadcast moved to Ruby 4.0.5 in the same release. Nothing you’ll see, everything you’d notice if it went wrong: the same maintenance work that keeps a self-hosted app safe to leave running on your own server for years.

The release notes still exist, still get written carefully, and are still there for anyone who wants the full list. The tour isn’t a replacement for them. It’s an acknowledgement that a link in a file nobody opens is not communication — and that if I want you to get the value you already paid for, the software has to point at it.

See the upgrading documentation for how upgrades work, or read why Broadcast is a one-time license — the reason every one of these features arrives in a release you already own.