Release notes: how to write them so customers read them
What release notes are, what goes in them and how to write notes customers read. With a structure you can reuse on every release.

On this page
Good release notes tell each customer three things: what changed, whether it affects them and what they need to do now. Start from that last question. Sort every change by what it asks of the customer, put the changes that ask the most at the top and check each entry in the real product before it ships.
Release notes are the short, customer-facing summary of what changed in a release of your product, published when the release goes out.
On 16 November 2026, we read three of the pages that rank for "release notes": Wikipedia's entry, the Good Docs Project's template guide and Appcues' guide with 13 examples. All three list the parts a release note should have. Wikipedia lists "end-user impact" among the information a note can include. The Good Docs Project gives features that need a configuration change their own section. Appcues says to answer "does this affect me?" in the first sentence of each entry, and has support review the notes before they're published. None of the three says to follow each entry in the build that will ship, and none sorts the changes by what each one asks of the customer.
What are release notes?
Software release notes describe what changed in one release: new features, changes to how existing features work, fixes and anything being removed. Wikipedia defines them as notes that "describe important information about a distribution of a hardware or software product." For a SaaS product, publish them on a page of their own, and send the parts that matter by email or inside the product.
A release note is written for the people who use the product, not the people who built it. That's the line between release notes and a changelog.
Who reads release notes, and what do they want to know?
Customers read release notes, and so do the people who answer their questions. Each reader wants something different.
| Reader | What they're looking for |
|---|---|
| A customer who uses the product every day | Does anything I do work differently now? |
| An account admin | Is there a setting I need to change, or a deadline I need to meet? |
| A customer who asked for a feature | Is the thing I asked for here? |
| Your support and success team | What will customers ask about this week? |
| Your sales team | What can I tell a buyer that's new? |
| A buyer comparing products | Is this product still being worked on? |
Appcues' guide tells you to write for the reader who scans. So the first line of each entry has to answer the question in the right-hand column on its own.
What goes in a release note?
Every release note needs a header, a one-line summary and one entry per change. Each entry says what changed, what the customer does now and where to learn more.
- Header: the product name, the release date and the version number if you use one.
- Summary: one sentence on what the release is about and who it affects.
- Action needed: anything a customer must do, and by when. This goes first when there is any.
- Changed: features that work differently, including anything that moved on screen.
- New: features a customer can use now.
- Fixed: bugs, described as what the customer saw before and what happens now.
- Known issues: anything still not working, with a workaround if there is one.
- Removed or retiring: features that are gone or will be, with the date.
- Where to get help: a link to the help docs, the tutorial or support.
You don't need every section every time. A release with two fixes is a header, a summary and two lines.
How to write release notes, step by step
Steps 2 and 5 are the two that none of the three pages we read covers.
- List every change from the build.
- Sort each change by what it asks of the customer.
- Write each entry from the customer's side.
- Order the note by what each change asks.
- Check every entry in the real product.
- Publish the note with the help docs and tutorials it points to.
Step 1: List every change from the build
Start with the full list of what's shipping: tickets, pull requests, the product manager's notes. Then open a build that has the release in it and click through each change yourself. Ticket titles are written for engineers, and a ticket can describe a screen that changed again before it shipped.
Leave out changes no customer will ever notice, such as a refactor or an internal tool. Keep anything a customer can see, set or rely on.
Step 2: Sort each change by what it asks of the customer
For each change, ask one question: what does the customer have to do differently after this release?
| What the change asks | Example | How much space it gets |
|---|---|---|
| Act, by a date | An old integration stops working at the end of the month | The top of the note, with the date and the steps |
| Work differently | The Export button moved from Reports to the top bar | A short entry with where it is now |
| Learn something new | A new way to edit many invoices at once | An entry with a link to a tutorial or help article |
| Nothing | A page loads faster, or a bug is fixed | One line under Fixed or Improved |
A release can have changes in every row. The sort tells you what goes first, which entries need more than a line and which ones need a help doc or a tutorial behind them.
Step 3: Write each entry from the customer's side
Each entry gets a short title that names the change in the customer's words, then two or three sentences.
- Say what the customer can do now, or what's different, in the first sentence.
- Name buttons and settings exactly as the screen names them.
- Say who it affects if it's not everyone: a plan, a role or a platform.
- Give the one action needed, if there is one, and the date.
- End with a link to the help article or tutorial for anything that takes more than a sentence to learn.
The Good Docs Project's guide suggests writing in the present tense, except for bug fixes, which go in the past tense. Both it and Appcues give the same advice for fixes: describe what the customer saw before and what happens now, not how the bug was fixed. "Reports no longer show yesterday's date in the morning" tells a customer something. "Fixed a time zone bug" doesn't.
Step 4: Order the note by what each change asks
Put "Action needed" first, then the changes that make people work differently, then new features, then fixes. A customer who reads only the top of the note should still see anything they have to act on.
Teams used to leading with the biggest new feature may find this order odd. When there's a feature you want everyone to notice, give it the summary line. The entries below still follow the sort.
Step 5: Check every entry in the real product
Before the note goes out, someone who didn't write it follows each entry in the build that will ship. Every button name, menu path, setting and date in the note should match the screen. If a label changed after the note was drafted, fix the note.
Check the links too. A link to a help article that hasn't been updated sends the customer to the old way of doing things.
Step 6: Publish the note with the help docs and tutorials it points to
A release note is short by design, so it leans on the help docs and tutorials behind it. Those need to be live on launch day too. Go back to the sort from step 2.
- Every "Learn something new" change needs a help article or a tutorial to link to.
- Every "Work differently" change probably makes an existing help article or video wrong. Find those and update them.
- Every "Act, by a date" change needs the steps written out somewhere a customer can follow them.
At SWFTMENT, we ask for the release notes ten days before launch, along with test access to the product. The launch video, tutorials and help docs for the release go live on launch day.
A worked example: one release, written two ways
This release is invented, for an imaginary invoicing product. Here's how the changes look on the engineering list, and how they read once they're sorted and written for the customer.
| From the engineering list | In the release note |
|---|---|
| Deprecate v1 invoices endpoint | Action needed: the old invoices API stops working on 31 March. If your accounting tool connects through it, switch to the new connection in Settings before then. |
| Move export CTA to global nav | Changed: Export has moved. It's now in the top bar on every page, instead of on the Reports page. |
| Bulk edit for invoice list | New: edit up to 50 invoices at once. Select them in the Invoices list, then choose Edit selected. [link to tutorial] |
| Fix TZ offset in report date filter | Fixed: reports opened early in the morning sometimes showed the previous day's date. They now show the right date in your time zone. |
The finished note, in the order step 4 sets:
Invoicing release, 3 March
This release adds bulk editing and moves Export to the top bar. If you connect an accounting tool through our old API, there's one thing to do before 31 March.
Action needed: the old invoices API stops working on 31 March. If your accounting tool connects through it, switch to the new connection in Settings before then. [link to steps]
Changed: Export has moved. It's now in the top bar on every page, instead of on the Reports page.
New: edit up to 50 invoices at once. Select them in the Invoices list, then choose Edit selected. [link to tutorial]
Fixed: reports opened early in the morning sometimes showed the previous day's date. They now show the right date in your time zone.
Behind this note, three other pieces ship the same day: the steps for switching connections, a short tutorial on bulk editing and an updated help article for exporting, because the old one still says to open Reports.
Release notes, changelog or launch video: which does what?
Release notes, a changelog and a launch video all cover a release, but each one has a different reader and a different job.
| Release notes | Changelog | Launch video | |
|---|---|---|---|
| Its job | Tells customers what changed and what to do | Keeps a record of every notable change | Shows the one change that matters most and why |
| Who it's for | Customers and the teams who support them | Developers, admins and anyone checking the history | Customers, on launch day |
| How long | A few lines per change | One line per change | Short: ours run three minutes or less |
| When to use it | Every release | Every release | When one change is worth showing to every customer |
Keep a Changelog describes a changelog as "a curated, chronologically ordered list of notable changes for each version of a project." Its six types of change (Added, Changed, Deprecated, Removed, Fixed and Security) are a good starting list for release notes, too. Appcues notes that the two terms blur in practice, because the changelog is usually where release notes live. One page can do both jobs, as long as each entry is written for the customer.
Release notes best practices for SaaS teams
- Give the notes one owner. The Good Docs Project's guide says many teams can contribute, but release notes "must have a single owner." Appcues says engineering supplies the raw material and a product manager or product marketer owns the final draft.
- Publish in the same place every time. Link to it from inside the product, so customers don't have to search for it.
- Keep a steady rhythm. If you ship every week, a short note every week is easier to follow than a long one every quarter.
- Date every note, and keep the old ones up. Customers and your support team look back to find out when something changed.
- Correct mistakes in the open. If a note was wrong, fix it and add a line saying what changed.
- Tell the people who asked. If a change came from customer requests, let those customers know it's out.
Questions people ask about release notes
What is a release note?
A release note is a short, customer-facing summary of what changed in one release of a software product. It lists new features, changes to how things work, fixes and anything being removed. A good one also tells each customer whether the change affects them and what they need to do.
Is it release note or release notes?
Both are correct. "Release notes" names the whole document for a release (Wikipedia's entry uses the plural), and "a release note" can mean that document or a single entry in it. For the page on your site, "Release notes" and "What's new" both work.
What should release notes look like?
Release notes should look like a short page you can scan. Start with a header that has the product name and date, then a one-line summary, then entries grouped under labels such as Action needed, Changed, New and Fixed. Each entry has a title in the customer's words, two or three sentences and a link to more help where it's needed.
Who writes release notes?
That depends on the company. In some, the product manager writes and owns them; in others, marketing or the documentation team does. Either way, engineering should supply the list of changes, and one named person should own the notes and check them against the product.
How long should release notes be?
Release notes should be as long as the changes need and no longer. A fix gets one line. A change to how something works gets a short entry. A new feature gets two or three sentences and a link to a tutorial or help article, which is where the longer explanation belongs.

Keep reading.
Rather have it done for you?
Book a free 20-minute release review. We look at your next release and what your customers need to learn it. No pitch.
Book a release review


