Release notes help customers discover the improvements your team ships and understand how to use them. They also give you a natural way to return to someone who requested a feature and show them what their feedback helped shape.

For prospective customers, that history of updates shows how the product is developing. This matters especially for an early product, when someone is deciding whether it is growing towards what they need.

Give each update the care you would give a customer email. This guide shows how to turn shipped work into a clear announcement, with examples and a checklist to review before publishing. For inspiration, see the release notes examples, or copy a release notes template for a starting structure.

1. Choose the reader and the release

Decide who needs the update and which release or period it covers. Customers need to understand changes to the product they use. Support teams may also need rollout details, known issues and troubleshooting instructions.

Write down that audience before drafting. It helps you decide which changes deserve space and how much context to include. A customer announcement and an internal handover can refer to the same release while answering different questions.

2. Select changes that are available

Start with the work included in the release, then check what readers can actually use. Confirm whether a feature is generally available, in a limited rollout, behind an administrator setting or restricted to a plan. Say which conditions apply.

Include fixes when customers can recognise the problem they address. Describe a corrected export error as a fix; calling it an “improved experience” makes the change less clear. Leave out internal maintenance that has no useful consequence for the audience.

You can be positive and personable without hiding the problem. Use humour when it fits your voice and the situation, but keep the explanation clear when a bug has disrupted someone’s work.

For each candidate, gather the customer problem, the resulting behaviour, availability and any action the reader needs to take. If those facts are missing, ask the person responsible for the change before writing a confident announcement.

Slack makes room for personality

Slack’s example uses a playful explanation for an activity-indicator fix, then switches to a straightforward apology for a VoiceOver problem. The lesson is knowing when a joke helps and when readers need a clear account of what was fixed.

3. Turn the work into a reader outcome

Use an internal ticket to find the facts, then write a title and description for the reader. A useful entry says what changed, why it matters and where to find it.

For example, imagine a reporting app has shipped saved filters:

Before · Internal summary

Persist report filter state in saved views.

That is implementation language. A customer-facing draft could say:

After · Customer-facing draft

Save report filters for next time

Save a report view with the filters you use regularly, then reopen it without setting them again. In Reports, choose your filters and select Save view. Saved views are available to workspace members.

Microsoft Teams keeps the explanation concise

The Teams example pairs an action-led heading with a short explanation and the controls needed to use the change. Aim for that combination of benefit and practical detail. Short copy still needs to answer the reader’s question.

4. Give readers a next step

A small change may only need a sentence. A new workflow may need a screenshot, a short demonstration or a documentation link. Add the detail that helps someone use the change, rather than making every entry the same length.

Link to the relevant instructions instead of a documentation homepage. If readers must migrate data, enable a setting or change a process, explain the action and timing directly. Keep known limitations beside the affected feature.

Front points readers to the right help

Front explains what its OneLogin integration changes, then links to the relevant provisioning and teammate-group guides. The announcement stays focused while readers who need setup detail have a clear next step.

5. Organise the update for scanning

Put the most relevant change first. Group related work by customer task, product area or change type, whichever helps this audience find what matters. Use clear headings and keep smaller fixes concise.

Avoid a long introduction about how hard the team worked. Readers should quickly see whether the update affects them. For longer updates, a short summary and links to sections can help.

Keep the structure familiar across releases, but remove empty sections. A release with two useful fixes does not need a new-features section or an invented theme. The template guide provides editable structures for customer, internal and email updates.

When several changes support the same customer goal, have product and product marketing agree on that story together. Explain the connection rather than presenting a dozen unrelated tickets. Keep the language, colours and imagery recognisable across updates; categories or familiar icons can help navigation when their meaning is clear.

GitHub makes relevant changes easier to find

GitHub’s example uses categories and product-area tags to help readers find changes relevant to their work. Choose labels your customers recognise and apply them consistently so the archive stays useful after the launch announcement.

6. Review the facts and the wording

Before publication, have the appropriate people check the update:

• Is each change available to the readers receiving it?
• Do names, settings, screenshots and links match the product?
• Does each entry explain a recognisable outcome or problem?
• Are limitations and required actions easy to find?
• Have internal details and unsupported claims been removed?
• Are fixes described clearly, without disguising what went wrong?

Read the draft once without looking at the original tickets. If a sentence only makes sense with that background, add the missing context or rewrite it.

Publish the reviewed update

Choose a destination the audience can access and return to. After publishing, check the final page, links and any announcement message. Keep the release date and availability clear so an older update is not mistaken for a current rollout.

If your delivery work is in Jira, follow the Jira release-note publishing workflow. Released Hub AI release notes can help draft from selected Jira work; your team still reviews the facts and the final wording.

If you are choosing how to generate and distribute updates, compare the automated release notes apps for Jira. Keep that tool decision separate from the writing task: whichever workflow you use, the published note should tell readers what changed and what to do next.

Publish release notes your customers will read

Select shipped Jira work, turn it into a clear draft, and publish the approved update where customers will find it.

Explore AI release notes →