Release Notes Strategy: Somebody Read 32,425 Notes. Only 2 In 100 Told The Reader What To Do.

When a small software team ships something, somebody writes a short note about it. It might be a release on GitHub. It might be a changelog page, which is just a list of changes kept in one place. It might be the "What's new" text in an app store.

For a team of two to ten engineers, that note is most of the marketing they do. Nobody else is writing anything. So a release notes strategy is simply this: deciding what that note says, and who it is for.

Researchers have now counted what these notes say. The answer is not what most teams expect.

What you will get from this:

• What 32,425 real release notes actually say, and what they leave out.
• Why the person who built the change cannot see the problem.
• A five minute test you can run on your next note, for free.

The Note You Wrote Last Friday

Picture a normal Friday. Someone on your team merges a change. Merging means the new code is now part of the product.

Then someone writes the note. Often it is the same person. Often it takes them five minutes.

GitHub can now write it for you. Its "Generate release notes" button lists the titles of the changes that went in (GitHub Docs). So the note is often a list of what the team did, in the team's own words.

Most teams believe good work speaks for itself. If the change is good, people will notice.

The research says something different. People do look for the note. But the note they find was not written for them.

What 32,425 Real Release Notes Actually Say

Five researchers read 32,425 release notes from 1,000 projects on GitHub. They sorted every note by what was inside it. The study is by Bi, Xia, Lo, Grundy and Zimmermann. It was published in IEEE Transactions on Software Engineering in 2020 (the paper, free copy).

Here is what they found. One note can hold more than one kind of thing. So the numbers add up to more than 100.

• 79.3 percent listed bugs that were fixed.
• 55.1 percent talked about new features.
• 2.1 percent told the reader something they had to do.

Look at that last line again. About 2 notes in 100 said "you need to do this".

There was one more count. 71.5 percent of all the information was written for people who read the code itself.

Here is what that looks like. A team writes: "Fixed race condition in sync worker." Most customers do not know what that means. The same change, written for a customer: "Your files now save properly when two people edit at once."

The readers in the study said the same thing. They said notes had too much about bug fixes. They wanted more about new features.

One fair limit. The projects were popular ones, with over 6,000 stars each. Most of the 314 people surveyed were technical people. The study had very few ordinary users in it. So we do not know how big the gap is for them.

The Copied Note

A second study looked at phone apps. Yang, Hassan, Zou and Hassan studied 69,851 updates of 2,232 top free apps on Google Play. The updates ran from April 2016 to April 2019 (Empirical Software Engineering, 2022, free copy).

They found that 59 percent of the apps tended to reuse their old notes. So the app changed, but the note stayed the same.

You have seen this on your own phone. "Bug fixes and performance improvements." It tells you something changed. It does not tell you what.

The researchers grouped the apps by how they wrote. In the group with short, reused notes, 56 percent of notes only said a general bug fix. Another 23 percent only said a general improvement.

Users noticed. The same study found people leaving bad reviews about the note itself.

Why You Cannot See It

Here is the strange part. The people writing these notes are not lazy. Most of them are careful engineers. So why does it keep happening?

In 1990, a Stanford student named Elizabeth Newton ran a simple game for her studies. One person tapped out a famous song on a table with their knuckles. Songs like "Happy Birthday". The other person had to guess the song.

Before they started, the tappers guessed how often the listener would get it right. They said half the time.

Then they played. 120 songs were tapped. The listeners named 3 of them. That is 2.5 percent.

Chip Heath and Dan Heath told this story in Harvard Business Review in December 2006 (HBR). They call it the curse of knowledge. Once you know something, it is very hard to imagine not knowing it.

The tapper hears the whole song in their head. The listener hears only knocking.

Your update note works the same way. You read "fixed race condition in sync worker" and you see the whole problem. Your customer sees only the knocking.

This is also why reading your own note again does not help. You will always hear the tune.

Where the Fix List Is Exactly Right

None of this means the list of fixes is bad. For some readers, it is exactly right.

If your users are developers who build on your code, they need the fixes. The GitHub study found this too. For code libraries and developer tools, fixed issues were the most common thing in the notes. The researchers said these readers are more likely to want that detail.

The person who reported a bug wants to see it named as fixed. So does your own support person, who has to answer questions the next day.

And the notes are usually correct. Wu, He, Xiao, Gao and Zhou studied 1,731 complaints about release notes on GitHub (ICPC 2022). They found writers leave things out more often than they get things wrong. The thing most often left out was a change that breaks something people rely on.

So keep the list. Just do not stop there.

What Changed for the Apps That Changed

The phone app study had one more finding. It is the most useful one.

The researchers found 53 apps that clearly changed how they wrote their notes over time. They read those notes by hand.

About a third of them, 34 percent, changed for one reason. They stopped listing what they had built. They started teaching people how to use it.

Here is what that looks like. "Added export feature" lists what was built. "You can now save your report as a spreadsheet. Tap the share button." That one teaches.

The researchers also saw something about ratings. Most apps that moved to longer, fresh notes got better ratings.

Be careful with that point. It is a pattern, not proof. Apps that write better notes may also be better run in other ways. The study does not show that the notes caused the ratings.

What it does show is what careful teams did when they changed. Many of them started teaching.

A Simple Release Notes Strategy: One Test And Three Sentences

You cannot read your own note the way a stranger does. So ask someone else to read it.

Here is the test. It takes five minutes and costs nothing.

1. Write your note the way you normally would.
2. Give it to someone who was not in the room when the work was done. A friend, a family member, or someone from another team.
3. Ask them two questions. What can you do now that you could not do yesterday? Do you have to do anything?

If they can answer both, the note works. If they stop, or guess, rewrite it.

Then add three plain sentences at the very top.

• What you can do now. "You can now save your report as a spreadsheet."
• Who it is for. "This is for anyone who shares reports with their team."
• What you need to do. "Nothing. It is already there." Or, if something will break: "Update your app before Friday."

Keep your full list of fixes underneath. The developers and the support team still need it.

That is the whole change. You keep the fixes, and you add three sentences on top.

Where The Note Has To Be For Anyone To See It

A good note still has to be found.

In the study of 1,731 complaints, 17.65 percent were about finding the note. Some people could not find where it lived. Some were never told a new version existed.

People do go looking. The phone app study mentions a survey on Reddit. Of 372 people who answered, 311 said they read release notes. Most read them to find out what is new or what changed. People who answer a survey about notes are more likely to read notes. So treat that number with care.

People are also nervous about updates right now. In April 2026, UserTesting and Talker Research asked 4,000 adults in the US, UK and Australia. 78 percent of Americans said they avoid updating unless they have to (UserTesting, June 2026). UserTesting sells research tools, and this was their own survey.

That is why the three sentences matter. A person who is already unsure looks for one good reason to trust the change.

So put the note where your users already are. The screen they see when they log in. The email they already open. And send it straight to the person who asked for the change.

Frequently Asked Questions

What is a release note?

A release note is a short message that says what changed in a new version of your software. It can live on GitHub, on a changelog page, in an app store, or in an email.

Should I stop listing bug fixes?

No. Keep them. Developers who use your code need them, and so does your support team. Just put three plain sentences above the list.

Can I let a tool write my release notes?

You can. A tool that lists the titles of your changes gives you what most teams already write. That is a list of what the team did. You still need to add what the reader can now do.

How do I know if my note is clear?

Give it to someone who was not in the room. Ask what they can do now, and whether they need to do anything. If they cannot answer both, rewrite it.

Where do these numbers come from?

From three studies. Bi and colleagues, IEEE Transactions on Software Engineering, 2020. Yang and colleagues, Empirical Software Engineering, 2022. Wu and colleagues, ICPC 2022. The tapping game is Elizabeth Newton's, Stanford, 1990, as told by Chip and Dan Heath in Harvard Business Review. Each one is linked where it is used above.

One question for you. We would really like to know the answer.

The last thing your team shipped, how did your first user find out about it?