# How to Write a Changelog Users Actually Read (With a Template) A changelog is the simplest proof that your product is alive. Customers check it before they renew, prospects skim it during evaluation, and support teams link to it when a bug they reported is fixed. Yet many changelogs are either a dump of commit messages or a page that hasn't been touched in a year. This guide covers how to structure entries, which categories to use, how often to publish, and gives you a template. At the end we show how to publish it as a hosted page and an in-app widget with [Nitrozen](https://nitrozen.io). ## Who the changelog is for There are two audiences, and they want different things: - **Developers integrating your software** want precise, versioned lists of what was added, changed, deprecated, removed and fixed. The community convention [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) is written for this audience. - **Customers using your product** want to know what they can do now that they couldn't before, and whether anything they rely on changed. Most SaaS teams need the second kind, a **product changelog**, and sometimes the first as well for an API or SDK. Decide which you're writing before you start, because it changes the language. (More on that in [changelog vs release notes](https://nitrozen.io/blog/changelog-vs-release-notes).) ## Anatomy of a good entry Every entry should answer three questions in its first two sentences: **what changed, why it helps, and where to find it**. 1. **A benefit-led title.** "Export reports to CSV" beats "Export improvements". "Fixed login loop on Safari" beats "Bug fixes". 2. **A date** (and a version number if customers install your software). 3. **A category.** Readers scan for what affects them. 4. **One to three sentences** written from the user's side: what they can do now and how. 5. **A visual** for anything they'll see: a screenshot or short GIF. 6. **A link** to the docs, setting or feature. ## Categories that work Keep a small, fixed set so the log stays scannable. Keep a Changelog uses *Added, Changed, Deprecated, Removed, Fixed* and *Security*. Product changelogs often simplify this to: - **New:** a feature that didn't exist before. - **Improvement:** an existing feature got better. - **Fix:** something broken now works. - **Announcement:** pricing, policy, deprecations or company news. Whatever you pick, use the same labels every time. Nitrozen ships with New, Improvement, Fix and Announcement as colour-coded badges for exactly this reason. ## Writing style - **Lead with the outcome, not the implementation.** "Dashboards load faster on large accounts" instead of "Refactored the query layer". - **Use "you".** It forces you to describe a user-visible result. - **Be specific.** "Search now matches partial email addresses" is useful; "Improved search" isn't. - **Admit bugs plainly.** "Fixed a bug where invoices showed the wrong currency" builds more trust than vague wording. - **Skip internal jargon.** Ticket numbers, branch names and codenames belong in internal notes. - **Flag breaking changes first** with the action required and a deadline. ## How often to publish Consistency matters more than volume. Pick a rhythm you can sustain (every release, weekly or every two weeks) and stick to it. If a week is quiet, batch small fixes into one "quality improvements" entry instead of going silent. A changelog that hasn't moved in months makes an active product look abandoned. The easiest way to stay consistent is to make the entry part of "done": whoever ships a user-visible change writes a two-line draft while the context is fresh. Teams that release through GitHub can automate this; see [automating your changelog from GitHub Releases](https://nitrozen.io/blog/automate-changelog-github-releases). ## Template Copy this for each entry: ```markdown ## [Benefit-led title] **Category:** New | Improvement | Fix | Announcement **Date:** YYYY-MM-DD [One sentence: what you can do now.] [One sentence: why it matters or what problem it solves.] **How to use it:** [Where to find it, e.g. Settings → Notifications → Email digest.]  [Link to docs →] ``` ### Example ```markdown ## Get a weekly email digest of new comments **Category:** New **Date:** 2026-10-28 You can now receive one summary email each Monday instead of a notification for every comment. It's on by default for new workspaces and off for existing ones. **How to use it:** Settings → Notifications → Weekly digest. ``` ## Make it easy to find A great changelog nobody sees doesn't help. Put it in at least three places: 1. **A public page** at a memorable URL such as `/changelog` or `changelog.yourdomain.com`, linked from your footer and help centre. 2. **Inside the product**, through a "What's new" widget, so active users see updates without leaving the app. See [how to add a what's new widget](https://nitrozen.io/blog/whats-new-widget). 3. **Where customers already are:** link notable entries in your newsletter, social posts and support replies. ## Publish it with Nitrozen [Nitrozen](https://nitrozen.io) is a changelog platform built for this workflow: - Write entries in **Markdown** with category badges. - Publish to a **hosted public changelog page**, with **custom domain** support on paid plans. - Show the same entries in your app with an **embeddable widget** added via one script tag. - Automate from your pipeline with the [REST API](https://nitrozen.io/docs/api), SDKs for [Node.js](https://nitrozen.io/docs/node-sdk), [Python](https://nitrozen.io/docs/python-sdk) and [Go](https://nitrozen.io/docs/go-sdk), a [GitHub Action](https://nitrozen.io/docs/github-action), or let an AI assistant draft entries through the [MCP server](https://nitrozen.io/docs/mcp). The free plan includes one project, five entries a month, a public page and the widget, so you can start today. [Create your changelog free →](https://nitrozen.io)