Brainstorming release notes to be better

Hey team,

Over the past couple of years (since Sally stopped writing our release notes) we’ve worked hard to make them more useful and also well integrated into our delivery process.

But talking about them with @Rachel and @sauloperez in BCN, we believe they could be even better.

So I’m creating this topic for us to gather great examples of how other software companies communicate to their users about the changes they implement, that can inspire us to start doing ours in an even more user-friendly way :smiley:

Feel free to add examples to this topic if you know of any that you believe are great :ok_hand:

1 Like

Notion release notes

These guys put out a release every couple of weeks, and have a place where they announce and explain the changes.

Their releases seem to include a particular feature alongside of the bug fixes and small improvements.

I really like how they use screenshots and videos to explain how the new features work. And they link to further information where they have it (e.g. userguide).

Slack updates

Slack have in-application notifications about changes to their software that you can access via the main menu. This section has a small blurb about the change and then links to a blog post when more detail is available.

I really like the way they don’t talk specifically about releases, but just focus on what the user can now do and don’t do a big list of things but break them out into their own snippets. And they don’t necessarily talk about bug fixes but more about interaction/feature changes.

Github is also a great example of small and tailored blog posts aimed at explaning new features such as https://github.blog/2016-02-17-issue-and-pull-request-templates/.

They briefly introduce them and point to a documentation page for detailed information.

Besides, they also highlight the announcement of particular features taking what Slack does one step further.

Screenshot%20from%202019-07-16%2017-34-43

Another great example. Figma has a https://www.figma.com/whats-new/ where they focus on the most relevant feature changes with lots of images an explanations, linking to docs. At the same time they also have (and link from what’s new) a https://figmareleases.blogspot.com/ where they list the relevant changes included in each release but still described in a user-focused way with gifs and images.

Looks like something that would fit us perfectly.

In these examples, the things I think will work well for us:

  1. integration of screenshots or animation - don’t have to be as fancy and perfect as some of these examples - just a simple screenshot is great
  2. keep in mind who the communication is for - ie: primarily non-dev users I think - right?
  3. keep an archive/history (like in the blog posts) of previous releases - since we should anticipate that users will not race to reach each one as soon as we put it out
1 Like

It turns out ZenHub also has nice release notes

oops I forgot to post, the Slack ones’ I’ve posted on the communication channel https://slackhq.com/introducing-a-more-efficient-slack-desktop-experience

We need to come up with an actionable item to turn this into a reality. Thoughts?

@sauloperez I guess it depends on when we will create a release we want to speak about? Maybe after performance?

but I guess we can discuss what we exactly want from our release notes given all these examples. Then, we’ll change our releases process accordingly. Let’s see what @danielle has to say.

We need to run an experiment on this as part of the release testing next steps.

The problem we have is capacity to do this thinking and change work alongside of everything else that people are doing. It needs to be prioritised in the pipe just like everything else (product management, roadmap creation, finding funds, bug fixing, performance work, API work, etc etc etc).

Does this fit in the ATAP world @rachel? I’ve purposefully steered clear of that world as I have trouble enough keeping up with all the other meetings and other stuff we have…but it’s a comms thing, but also related to the platform work. And the roadmap building work (which also isn’t on any to do list right now).

@danielle actually @sauloperez @Jen and me have an ATAP action of moving this forward :slight_smile: so it is in the ATAP world.
At last ATAP meeting, Pau was still on holiday so we decided to move forward when everyone would be back and gave this a low priority. But I agree now we are actually in a good place to move forward and increase priority on this. Next ATAP meeting is Tuesday. Can you make it @sauloperez ?

I’m very sorry I’d really like to attend but we have holidays in Barcelona. It’s the patron day and I have some plans. What about the day before?

@sauloperez ok let’s try that and then I will talk with @Jen on Tuesday on how we move forward as a team?

Yeah better. I wanted to say I won’t provide so much that justifies changing the date.