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”.

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 communication¹. 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 5². 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.

• Feer of losing data: There is nothing scarier than losing a record of changes over time. With chronological release notes, you can keep the peace of mind that changes are properly logged. And if you ever need this information for any reason, you know where to find it. This might also be a reason why we love using automatic backup tools, storing files with old designs, keeping infinite backlog, etc. Because you never know when you need it. This feer is a powerful behavior driver.
• Enforced accountability: When there is a clear expectation that every change has to be documented it inevitably enforces accountability on the team. Although, it’s worth mentioning that such forceful accountability enforced in such a way will only hurt over the long term.
• Regulatory requirements: When you sell software to huge enterprises, the security requirements are high. Having a document with all the changes in the product would be helpful here.

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:

• Segment the information: To increase the readability of release notes, you need to give people what’s important. Those segmented release notes can live in many different documents depending on the group. You can still have general Release Notes for those who are interested. But this time, it’s not the only option.
• Learn what’s important: The first step before segmenting information is to answer what people need to know. You can reach out to teams across the company, have a set of separate meetings to learn more about their needs. That’s internal user research.
• Combine static universal information with chronological updates: Before all the chronological updates in release notes, add a section with universal links and information. Whenever people need this information, it won’t be scattered across the timeline of updates.
• Give people information on their terms: It’s important to understand the chance anyone would read the message if you send it at night-time is extremely low. Consider people’s time zone and preferences. Some prefer getting information early in the morning. Others prefer evening time after work to read through updates.
• Maintain Release Notes FAQ: Questions that people ask regarding information in release notes should be documented inside the release notes. It will significantly improve the usefulness of the document. And decrease the number of repeating questions over time.

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

---