Template · Updated
Release notes template
Release notes are read by your most engaged customers and skimmed by everyone else. Written well, they announce what's new and send people to the right help article. This template keeps them short and customer facing.
Short answer
Good release notes tell customers what they can do now that they couldn't before, in their words, not yours. Lead with the most important change, group the rest as new, improved, and fixed, link the help article for anything that needs explaining, and leave out internal changes customers won't notice.
When to use this template
Use this template for each entry in your changelog or “What's new” page, whether you publish weekly, per release, or monthly. One entry can cover several changes; keep each change to a sentence or two and link out for detail. If you also send release emails or in app announcements, write the release note first and reuse it, so every channel says the same thing and links the same help article.
What goes in it
A headline about the biggest change
Name the change customers care about most: “Recurring invoices can now end on a date.”
Why it matters
One or two sentences on what the customer can do now.
New, improved, fixed
Group the rest so readers can skim. Use plain verbs and the names customers see in the product.
Links to help articles
Every change that needs explaining links the updated article, which means the article has to be updated first.
Date and nothing internal
Date the entry, and leave out refactors, dependency updates, and internal tools.
The template
Copy it into your help center editor and replace the bracketed parts.
# [Headline: the most important change]
[Date]
[One or two sentences: what customers can do now and why it matters.] [Learn how](link to help article).
## New
- [New capability, in customer terms.] [Article](link)
## Improved
- [What's better, and how they'll notice.]
## Fixed
- [The problem customers saw, now fixed.]Example: a Ledgerloop changelog entry
# Recurring invoices can now end on a date
October 6
Set an end date or a number of invoices when you create a recurring schedule, and Ledgerloop stops sending automatically. Learn how in Set up recurring invoices.
## New
- Late fees can be a percentage of the invoice, not only a flat amount.
## Improved
- The Invoices page loads faster for accounts with thousands of invoices.
## Fixed
- Payment reminders no longer go out for invoices marked paid by hand.Mistakes to avoid
- Writing in engineering terms (“refactored scheduler”) instead of what customers can now do.
- Announcing a change without updating the help article it affects.
- Listing every internal change, so the real news gets lost.
- Leaving out fixes customers reported; they want to know it's solved.
- Undated entries, so nobody can tell what changed when.
How to keep this article current
Release notes and help articles should change together, and they rarely do. usedocs reads each merged pull request or release and decides whether it's worth a changelog entry (and what kind: a fix, an improvement, or a feature) and whether it changes any help article. The changelog draft and the article edits come from the same change, so you can update the article before the release note links to it. The changelog appears on your help center and in the widget's What's new tab.
FAQ
How often should SaaS release notes be published?
As often as you ship customer facing changes; weekly or per release works for most small teams.
Should release notes include bug fixes?
Yes, fixes customers noticed or reported. Skip invisible internal fixes.
Should release notes link to help articles?
Yes, for anything that needs explaining, and update the article before publishing the note.
How long should a release note be?
A headline, a short paragraph, and a few bullets. Link out for detail.
Where should release notes appear?
On a changelog page, in the app or widget, and in an occasional email digest for bigger releases.
Who should write release notes?
Whoever shipped the change drafts one or two sentences; the docs owner edits them into customer language and links the article.
Should release notes mention who asked for a change?
Mentioning that customers asked for it is a nice touch. Don't name customers without permission.
Can release notes be generated from pull requests?
They can be drafted from them. A person should still rewrite them in customer terms and decide what's worth announcing.