Most release notes go unread. They get written at the end of a sprint, phrased in the language of the engineering ticket that produced them, and posted to a page nobody has bookmarked. The feature ships, the note goes out, and the customer who would have loved it never finds out it exists.
Good release notes are different. They are short, written for the person using the product, and structured so someone can skim five of them in thirty seconds and still come away knowing what changed. This guide shows you exactly how to write release notes like that, with a template you can copy, examples you can model, and a checklist you can run before every update goes live.
What are release notes?
Release notes are a short, user-facing summary of what changed in a product update: new features, improvements, fixes, and anything that affects how someone uses the product. They are sometimes called a changelog, product updates, or a "what's new" page. The format varies, but the job is always the same: tell your customers what is new in language they understand.
Release notes are not the same as an internal changelog or a git commit history. A commit message is written for the next developer. A release note is written for the person paying you. Confusing the two is the single most common reason release notes go unread.
How to write release notes in 7 steps
Here is the process, start to finish. You can run it in a few minutes per entry once it becomes habit.
1. Lead with the user outcome, not the internal change
Start every entry with what the reader can now do, not with what your team built. "Migrated the export service to a queue" means nothing to a customer. "Exports over 10,000 rows no longer time out" means everything. Same change, opposite readability.
A simple test: if your entry would only make sense to someone who works on your team, rewrite it.
2. Use a clear, specific title
The title is the part most people read, and often the only part. Make it a plain-language description of the change, not a version number. "Dark mode is here" beats "v2.4.0." "Faster search" beats "Search improvements." Be specific enough that the title alone tells the reader whether they care.
3. Add one or two sentences of context
Under the title, explain what changed and why it matters in a sentence or two. Who is this for? What problem does it solve? What can they do now that they couldn't before? Resist the urge to write a paragraph. If it needs more than that, link to the docs.
4. Categorize the change
Tag each entry as a New feature, Improvement, or Fix. This lets readers scan for exactly what they care about. Power users hunt for new features. Everyone else mostly wants to know their bug got fixed. Categories make both fast.
5. Write in your product's voice
Your release notes should sound like the rest of your product. If your onboarding is warm and friendly, your notes should be too. If you sell a developer tool, be precise and technical. A changelog written in a borrowed corporate voice reads as inauthentic, and people can feel it. For more on the voice trap, see why users ignore your release notes.
6. Link to more when it helps
The release note is the entry point, not the complete guide. For anything more than a small change, add one follow-up link: to the docs, to a tutorial, or directly to the feature in the app. Remove the friction between "I learned about this" and "I'm using this."
7. Publish the day it ships
Write and publish the entry the day the feature goes live, not in a batched monthly roundup. Freshness signals momentum. A steady drip of small updates makes a product feel alive in a way that a big quarterly post never does. If your process makes same-day publishing hard, that is a process problem worth fixing.
Release notes template
Here is a template you can copy for every entry. Fill in the brackets and delete anything you don't need.
[Emoji or category tag] [Plain-language title of the change]
[One or two sentences: what changed, who it's for, and why it
matters. Focus on what the reader can now do.]
[Optional: "Learn more" link to docs, a tutorial, or the feature.]
A worked example, filled in:
✨ New: Scheduled publishing
You can now write an update ahead of time and set it to go live at a specific date and time. Great for coordinating announcements with a launch. See how it works →
That is the whole shape. Title, context, optional link. Nothing more.
Release notes examples by category
Seeing filled-in examples is faster than any amount of theory. Here is what each category looks like done well.
New feature
🎉 Team workspaces
Invite your teammates and manage projects together. Everyone on your plan can now create and edit updates from one shared account.
Why it works: the title names the feature in plain words, and the body answers "what can I do now" in one sentence.
Improvement
⚡ Search is now 3x faster
We rebuilt search from the ground up. Results now appear as you type, even across thousands of entries.
Why it works: it quantifies the improvement and describes the felt difference, not the internal rewrite that produced it.
Fix
🐛 Fixed: exports timing out on large accounts
Exports over 10,000 rows were occasionally timing out. They now run in the background and email you a link when they're ready.
Why it works: it names the exact problem the affected users experienced, so the people who hit the bug know it is resolved.
For ten full changelogs worth studying, see our roundup of SaaS changelog examples worth copying.
Release notes best practices
A few rules that hold across almost every product:
- Write for the reader, not the writer. Describe the change in terms of the user's world, never the codebase.
- One change per entry. Don't bundle a feature, two improvements, and a fix into one wall of text. Split them.
- Keep it short. Two to four sentences per entry is plenty. Link out for the rest.
- Stay consistent. Same categories, same voice, same cadence, every time. Predictability is what turns a changelog into something people check.
- Avoid jargon and version numbers in titles. "v3.2.1" tells a customer nothing. Save version numbers for the body if they matter at all.
- Make it findable. A note nobody sees is a note nobody reads. Put it where your users already are.
That last point is the one most teams get wrong, so it is worth its own section.
Where should release notes live?
Writing good release notes is only half the job. If they sit on a page no one visits, they still go unread. The three places release notes belong, ideally all at once:
- A public changelog page. A hosted, SEO-friendly page anyone can visit and link to. This doubles as marketing: prospects checking whether your product is actively maintained will find a steady stream of updates.
- An in-app widget. A small "what's new" button inside your product that shows unread updates to logged-in users, right where they already are. This is what actually gets features noticed, because it reaches people in the moment they are using the thing you just improved.
- Email and RSS. For the users who want a push instead of a pull, let them subscribe.
Getting all three usually means either building them yourself or using a dedicated tool. If you want to build it in, we wrote a full guide on how to add a changelog to any web app in under ten minutes. If email is your main channel, our product update email templates will save you some drafting.
Frequently asked questions
What is the difference between release notes and a changelog?
In practice, very little. "Changelog" tends to describe the running, dated list of all changes, while "release notes" often describes the write-up for a specific release. Many teams use the terms interchangeably. Both are user-facing summaries of what changed, and everything in this guide applies to both.
How long should release notes be?
Per entry, aim for a clear title plus two to four sentences. If a change genuinely needs more explanation, write the short version in the note and link to a full doc or tutorial for the detail. The note is the headline, not the article.
How often should you publish release notes?
Publish the day each change ships rather than batching updates into a monthly post. Frequent, small updates make a product feel active and get individual features noticed. There is no minimum cadence, but consistency matters more than volume.
Should release notes include version numbers?
Only if your users think in version numbers, such as with developer tools or self-hosted software. For most SaaS products, a plain-language title is far more useful than "v2.4.0." If a version number matters, put it in the body, not the title.
Who should write release notes?
Whoever understands the change best and can translate it into user language. That is often a product manager, but engineers, designers, and support can all write great notes. The one requirement is that the writer thinks about the reader, not the ticket.
The takeaway
Release notes are read when they are short, written for the customer, categorized so they can be skimmed, published the day the change ships, and placed where users already are. None of that requires a big team or a marketing budget. It requires knowing who you are writing for and committing to publish consistently.
If you want a place to put all of this that takes minutes to set up, Patchlog gives you a public changelog page, an in-app "what's new" widget, an RSS feed, and email subscriptions from a single dashboard. It is free to start, so you can have your next release note live and in front of customers before the end of the day.