Skip to content

Guides

Write release notes customers actually read

Most release notes list changes in the team's words. Customers want to know what is different for them and what to do about it, and support wants fewer surprised tickets.

Last reviewed

Lead with the benefit

Open each item with what the customer can now do, not what the team built. One plain sentence is enough.

Group by what changed for them

Split notes into new, improved and fixed, and put anything that changes how people work at the top.

Warn about changes that need action

If a change needs a customer to do something, say so in its own line with the date. This is the line that prevents tickets.

Link the help article

Link each notable change to the help article that explains it. Update the article before you ship the note.

Brief support before the release

Send the team the notes a day early so they know what to expect and can add a saved reply for the likely question.

Watch the tickets after release

Count tickets that mention the change for a week. A spike means the note or the article missed something.

Questions

How long should release notes be?

As short as the change allows: one plain sentence for most items, with a link for detail.

Where should we publish them?

In a place customers already look, such as an in-app notice and a page on your site, plus an email for changes that need action.

Should support see them first?

Yes, a day before release, so the team can add a saved reply and answer without guessing.

Written by Flatdesk, a help desk for small support teams at one flat price per agent. Try it free for 14 days, no card.