A little thing about release notes

Why they’re important to us, and how we approach the writing of them at Slack

As long as there’s been software to update, people have been writing notes to tell you what’s gone into those updates. For the most part the readership was small — mostly IT managers — and the notes perfunctory. Today, though, everyone has a tiny computer in their pockets, and everyone is responsible for maintaining and updating their own software.

So, when we started working on Slack, and updating the service constantly, we thought about what we could do to make release notes more useful than the default…

March 23rd: v2.0.8
Bug fixes and Minor Improvements.

Because why stick to that, when they could contain real value, useful information, and the opportunity to connect a little bit, human to human, with the people who use Slack the most.

The funny thing about release notes is that they’re disposable, and temporary. They’re not required reading to use the app. You don’t have to read them at all: You can skip over them or have automatic updates and live in happy ignorance of their existence, safe in the knowledge your app will keep getting better and nothing more.

Or you can read them. And if you go to the bother of doing so, you should at least get something real and tangible out of them.

So we try to make them worth it for you. Release notes play a vital role in:

  • Informing users of new features.
  • Letting people know we’re listening to bug reports, and acting on them.
  • Educating people about the product.
  • Saying sorry (and meaning it) for not being as good as we want to be yet.
  • Celebrating the work our engineers put into every release.
  • Doing all of the above with some measure of charm.

It’s not about moving them too far away from what they are. We talked a lot about what our release notes should sound like — and there are lots of influencing factors, like The police blotter of The Arcata Eye, Corrections and Clarifications columns, that could make another post altogether. But essentially, we decided, they should take the basic facts, reduce jargon, put them into words people could relate to; words that might be lightly poetic and slightly absurd, but stopped short of grating, and were nothing less than informative.

This is how we go about it.

Make a list

As our teams work on a release, they keep a list of everything that goes into it. This gets edited down and divided into “things that are new” and “things that we fixed”.

New: Any new features or functionality, listed in order of excitement.

Fixed: Anything external facing, so “something that someone has experienced at some point, or that has been reported, or that was slightly hidden, but is frankly absurd, so interesting to share”.

Example: Our most recent iOS release notes

Check it twice

Some teams (particularly the mobile teams, whose releases come thick and fast) prefer to come up with a plain list so they can get on with the next iteration — other engineers are more into wordsmithery and take pride in producing a well-crafted note.

In either case, nothing goes out without being checked, tidied, clarified and fairy-dusted by an editor. There’ll be a bit of back and forth with the developers about anything that isn’t quite clear. Some examples, some demonstrations, and some stupid questions on the part of the editor, who approaches the notes with the mindset of a regular user. Having people from a less technical background helps at this point. Which is lucky, really.

Work out what was nasty, and when to be nice

Admitting we’re fallible and that we’re working on making things better is a matter of pride for us.

That means if something was a massive pain in the peach, or made people’s lives just a little worse, we don’t splatter it with jokes and pretty words to try and hide it. We say sorry, thank people for their continued patience, and let them know we’re working hard, all the time, to improve things.

Then we move things around — making sure there aren’t too many funny things in a row (or too many at all), that they have a rhythm that helps guide people through, sentences that sound as good in your head as they would out loud, and, if appropriate, end with the most ridiculously odd bug (or best line) to reward and thank people for getting all the way through.

Know when to stop

A weird bug meant that our previous release notes contained more jokes than information. We apologise for this abhorrent hiccough, and pinky-swear it will not happen again.

If you want to produce something that people will want to read, it’s only polite to make it enjoyable to read it. So in release notes — as in everything else we do — a large love for language, and a little humor, go a long way. Once you’ve gone that long way, it’s tempting to go further still, but we try and remind ourselves to hold back.

“Food tastes better with salt, but if you add too much salt you can’t taste anything else. Everyone likes a good guitar solo, but if a song is ALL guitar solos, most people will find it unlistenable,” as someone who was wise and fond of fun-spoiling said once.

It should be noted that, as with all things, the amount of salt is a matter of taste, even here at Slack, and the saltiness of our notes goes up and down seasonally due to the occasional debate behind the scenes, but this is the right and proper way to write. A lot of people care about these things and we get better, together.

The point is — and this never changes — that the content is the most important thing of all. Yes, we can have character — we’re Slack. But if character starts to overwhelm content, then the game is lost. No one will read them any more.

But for now: People do read them. And the more people read them, the more we put into writing them. And the more we put into writing them, the more people get out of reading them. Or that’s what we hope, anyway.


Anna Pickard does Words at Slack.