ic-arrow-left See All Notes
03 Nov 2020

The Internal Release Notes dilemma, and what can we do about it?

A lot of companies rely on external release notes to facilitate conversations with customers. Sometimes it’s the main channel for users to learn about the recent product updates. Companies like Notion, Linear, Pitch, Framer, and many others extensively use release notes for that purpose.

What’s usually overlooked is the internal version of this document. Internal Release Notes tend to be dense on information, contain more details, and help team members navigate through all the relevant links spread across the services.

High informational density of Internal Release Notes is a gift and a curse. The gift because everything is stored in one place. The curse because people need only a fraction of this information most of the time. Thus comes the challenge – because of overwhelming size, it might seem that nobody read Internal Release Notes.

A few weeks ago I posted a poll on Twitter, trying to understand how many people are using the Internal Release Notes. And, more importantly, how many find it efficient.

From 114 responses, it’s clear that at least 23% of people think nobody reads Internal Release Notes. And 36% don’t maintain it at all.

Moreover, from a quick search on Reddit, I found a few discussions about product communication in the team. Almost everyone mentioned Internal Release Notes as one of the solutions. And almost everyone agreed that “nobody reads Internal Release Notes”.

PMs on Reddit agree that nobody reads internal release notes

The intriguing question here is, why do people who believe nobody reads Internal Release Notes still maintain them and even suggest as a solution to others?

What’s the job of Internal Release Notes?

Internal Release Notes is just a tool. Being unsatisfied with the tool doesn’t mean it’s useless. It only means that it doesn’t work well for a specific problem (or a “job”). Is it reasonable to declare a hammer a useless tool because it can’t unscrew the screw?

It could be part of the answer to our question in the beginning. When a tool’s positive impact outweighs its inefficiency, you’d still use it and recommend it to others.

At the Release Notes core, there’s an idea that changes have to be documented in chronological order. So we can safely declare Release Notes a special case of Documentation. And like any other documentation, its main job is to communicate information. Let’s explore the positive and negative sides of release notes for this job.

The Communication job

Working in a team requires a lot of communication1. Especially in a remote work environment. People need to know about upcoming changes, troubleshooting guides, user research results, etc.

It might not be a problem for the team of 52. But with 20+ people, you might be in trouble without a sustainable information delivery channel. The scale is the problem here. With that many people, everyone can’t be involved in actual product development. So context gaps are created between product teams and customer-facing teams. Those who are talking with customers are no longer have the same information as people building the product.

Release notes sound like a scalable solution here. Keeping track of all the changes engineers & designers implemented and documenting it along with other information would be benefit customers facing teams enormously. It’s not an idea, though.

Core Problems with Internal Release Notes

  1. Readability problem: The nature of Internal Release Notes implies that we should keep all the information in one document (or chat / Slack channel). What sounds appealing produces negative side-effects later. This document becomes so large you can’t find anything there.
  2. Accessibility problem: Because different people need different information, putting everything in one place – makes it hard to find what’s important. And in this case, it’s natural for people to go for a path of lowest resistance – ask PM directly instead of reading release notes.
  3. Chronicle problem: Because release notes are structured around the time and date of a change, there is no room for universal information. For example, in the release notes, you may find a title like: “A feature X has deployed on Tuesday.”. Where should you put universal information like “User Research Results” and “Project Brief”? It’s usually the information the customer-facing teams seek.
  4. There is no space for questions/answers: People, who read internal release notes, often have the same questions. This inevitably leads to team members asking the same questions over and over again. With the standard structure, you can’t easily document those questions.

Despite the obvious issues, the format of Internal Release Notes hasn’t changed. The reason for that is because this format satisfies people who aren’t supposed to use release notes. So side-effects like “nobody reads Internal Release Notes” occur.

How can we improve Release Notes?

People not reading internal release notes is only a symptom of poor information architecture. With enough care, you can turn inefficient release notes into an advanced communication device for the whole team, not just a small group of people. Here are a few tactics to get there:

I’ve made a small template based on those suggestions, please feel free to use it: Internal Release Notes Template.

  1. Previously, I’ve written a whole article about internal communication. It’s all about understanding and adapting to people’s needs. If you want to have clear communication in the team, you’d need to understand people first. 

  2. Having 5 people in the team doesn’t automatically save you from communication problems. It still takes effort to make sure everyone knows what they need to. 

Hey there, thanks for reading!

I hope you enjoyed the article. You can reach out via Twitter if you have any suggestions or feel like chatting about product development.

Next week article: Prioritization framework for your next integration.

Stay in the Loop

If you want to get notified about new articles, add your email below.
I write weekly and send one email every two weeks.

Alternatively, use RSS instead by clicking the link https://curvedlayer.com/feed.xml