# How to write release notes people read

> Good release notes say what changed and why it matters, in plain words. Learn the structure, a before-and-after example and what to leave out.

Release notes tell people what changed and what to do about it. Written for the reader, not the team, they are short, plain and grouped by what matters.

Web page: https://kansohq.app/guides/how-to-write-release-notes

Updated: 5 October 2026

## Who release notes are for

Release notes are read by customers deciding whether to update, support staff answering questions and teammates checking what shipped. None of them want the commit history. They want to know: what is new, what is different, what is fixed and what do I need to do?

## A structure that works

- **Summary:** one or two sentences on what the release is for.
- **New:** what people can do now that they could not before.
- **Improved:** what works better.
- **Fixed:** what was broken and no longer is.
- **Known issues:** what is still wrong, so nobody has to find out.
- **Upgrade notes:** anything the reader must do, or watch for, before updating.

## Write about the reader, not the code

| Written for the team | Written for the reader |
| --- | --- |
| Refactored the sync module | Edits made offline now sync faster when you reconnect |
| Fixed null pointer in export | Exporting a project with no pages no longer fails |
| Added feature flag for boards v2 | Boards now load in under a second on large projects |

## Rules of thumb

1. Lead each item with the benefit, then the detail.
2. One line per change. If it needs a paragraph, link to a longer explanation.
3. Use the words your customers use, not your internal names.
4. Say plainly when something is removed or changed in a way that could break a habit or an integration.
5. Put the most important change first, not the most recent.
6. Date every release, and keep older notes where people can find them.

## What to leave out

- Internal refactors that change nothing for the reader.
- Ticket numbers and branch names.
- Every small fix. Group them: “Several small fixes to the calendar”.

## A complete example

**Release 3.4, 14 November (an invented example)**

> **Summary:** This release makes working offline reliable and speeds up large projects.
> **New:** Edits made offline are kept on your device and sent when you reconnect. A banner shows when a change has not been sent yet.
> **Improved:** Boards with hundreds of cards open in under a second. The calendar remembers whether you last looked at a day, a week or a month.
> **Fixed:** Exporting a project with no pages no longer fails. Several small fixes to the inbox.
> **Known issues:** Two people editing the same line offline will see the later edit win. We are working on a side-by-side view.
> **Upgrade notes:** Nothing to do. Refresh the page to get the new version.

## Tone and format

- Write in the second person: “you can now…”, not “we implemented…”.
- Plain words. If a customer would not say it, do not write it.
- Short lines that can be skimmed, grouped under the headings above.
- No marketing. A release note that exaggerates is read once.

## Where to publish them

Put release notes where customers already look: a page on your site, a section in the app and, for big changes, an email. Keep every release on one page or in one list, newest first, each with a date, so people can see what changed since they last looked. Keep the same notes where your support team can find them, since that is where questions come.

## Release notes in Kanso

Open the [release notes template](https://kansohq.app/templates/release-notes.md) in the project that holds the release. It has summary, new, improved, fixed, known issues and upgrade notes ready. The [release page](https://kansohq.app/product/releases.md) shows what shipped, so the notes can be written straight from the list of finished work.

## Questions

### What are release notes?

Release notes are a short, plain summary of what changed in a release: what is new, what is improved, what is fixed and anything the reader needs to do.

### How long should release notes be?

As short as possible: a summary and one line for each change that matters to the reader. Link out for detail.

### What is the difference between release notes and a changelog?

A changelog is a complete, dated list of changes, often kept for developers. Release notes are a reader-friendly summary of the changes that matter, usually written for each release.

### Should release notes mention bugs?

Mention fixes that readers noticed, and known issues that remain. Group minor fixes into one line.

## Keep reading

- [How to plan a software release, step by step](https://kansohq.app/guides/how-to-plan-a-software-release.md): Plan a software release in seven steps: fix the date, freeze the scope, split the work by team, track blockers and decide go or no-go. With a checklist.
- [A software launch checklist, step by step](https://kansohq.app/guides/software-launch-checklist.md): A software launch checklist for product, quality and go-to-market, plus launch day and what to do after. Copy it, give every line an owner and ship.
- [Release notes template: what changed and why | Kanso](https://kansohq.app/templates/release-notes.md): A release notes template with a summary, what is new, improved and fixed, known issues and upgrade notes. Copy it, or start it in Kanso.
- [Software launch checklist template to copy | Kanso](https://kansohq.app/templates/launch-checklist.md): A software launch checklist template covering product, quality and go-to-market, launch day and after launch. Copy it, or start it in Kanso.

## Parts of Kanso used

- [Kanso Releases](https://kansohq.app/product/releases.md): A release page gathers the work behind one date into sections, with an owner, a due date and a status on every line.
- [Kanso Docs](https://kansohq.app/product/docs.md): Pages with headings, to-dos, tables and code, kept inside the project they describe, next to its board and its release.

[Kanso home, with plans and prices](https://kansohq.app/index.md)