How to Write Release Notes Your Users Will Actually Read

The problem with most release notes

Most release notes look something like this:

v2.4.1 — Fixed null pointer exception in user authentication flow. Refactored token validation middleware. Updated bcrypt dependency to 5.1.1. Addressed edge case in session expiry logic.

Technically accurate. Completely useless to your users.

Your users don't know what a null pointer exception is. They don't care about bcrypt. What they want to know is: does this fix the thing that was annoying me? And more importantly: is anything new that I should know about?

The mistake most teams make is writing release notes for the people who ship the code — developers — instead of the people who use it.

Who actually reads your release notes

Before writing, answer this: who are you writing for?

Developers on your team read your Git commits, PR descriptions, and internal Slack. They don't need release notes.

Power users and early adopters want to know what changed and why. They care about new features, deprecated behavior, and anything that might break their workflow.

Regular users mostly don't read release notes unprompted — but they will if something changes that affects them, or if they discover it through a widget notification.

Prospective customers sometimes read your changelog to evaluate whether you're actively building. An active, well-written changelog signals a healthy product.

Write primarily for your power users and regular users. Keep it human.

The anatomy of good release notes

Lead with user impact, not technical implementation

Bad: "Refactored the authentication flow using a new token validation middleware"
Good: "Logging in is faster — we rewrote the authentication system from scratch"

The user cares about the outcome. Mention the implementation only if it's relevant to them (e.g., a security fix they should know about).

Use plain language

Write like you're explaining the change to a smart person who doesn't work in tech. Avoid jargon, acronyms, and internal project names.

Bad: "SSO integration now supports SAML 2.0 via Okta and Azure AD IdP federation"
Good: "Single sign-on now works with Okta and Azure Active Directory"

Group changes by type

• ✨ New — features that didn't exist before
• 🛠 Improved — existing features that work better
• 🐛 Fixed — bugs that were annoying users
• ⚠️ Breaking — changes that might affect how users work (always be explicit)
• 🔒 Security — changes that protect users

Lead with the most important item

Don't bury the feature your team spent three months on at the bottom. Your most significant change goes first.

Keep it short

Nobody reads a wall of text. If you shipped 30 things in a sprint, pick the 5 that matter to users and consolidate the rest into "plus a bunch of small fixes and improvements."

Format matters: hosted page vs. widget vs. email

Hosted changelog page: Can be longer. Users opted in by navigating there. Good for depth and context.

In-app widget: Short and skimmable. Users see this mid-session. One sentence per item, clear categories, clean formatting. The goal is "this is interesting" in 10 seconds.

Email notification: Slightly more conversational. A brief intro, the 3-5 biggest changes, a link to read more. Don't send a wall of text to someone's inbox.

A simple template

For most releases, this structure works:

[Release name or version] — [Date]

[One sentence summary of what this release focuses on]

✨ New
- [Item] — [one sentence user-facing impact]
- [Item] — [one sentence user-facing impact]

🛠 Improved
- [Item] — [one sentence]

🐛 Fixed
- [Item] — [one sentence]

The summary sentence is optional but valuable for major releases. "This update focuses on making search faster and fixing the issues some of you reported with file uploads" sets context before the user reads the list.

Ready to keep your users in the loop? Herald connects to GitHub, drafts changelogs with AI, and publishes to your users automatically. Start free trial →

The discipline problem

Most teams know how to write good release notes. The problem is doing it consistently.

Writing takes time. After a sprint, the team wants to ship, not document. Notes get written in five minutes at the end of a deploy, or not at all. After a few inconsistent cycles, the changelog goes stale, and nobody reads it anyway — which makes it even easier to skip next time.

The teams that maintain great changelogs do it by making the writing fast and structured:

• Draft based on merged PRs, not from memory
• Edit and publish in the same workflow as deployment
• Treat the changelog as part of the product, not a post-deployment chore

This is exactly why Herald connects to GitHub. Your merged PR history is your changelog history. Herald reads it and drafts the entry for you — so the consistency problem disappears.