Best Practices

Best Practices for Maintaining a Successful Changelog

Be consistent about how often you share updates

Pick a publishing cadence that is reasonable for your team, and stick to it. This is absolutely critical to the success of your changelog, because consistency builds trust with your audience. Over time, they learn that your changelog is the most reliable source of information when it comes to new product updates, not something that's constantly out of date.

...and about what you're sharing

The best product teams consult with customer-facing teams like support, customer success, and sales engineering to understand what types of updates customers typically like to hear about. Create internal guidelines on what information will be shared on the changelog. Then, formalize a system such as using a label called customer-facing in Jira to mark what issues should be communicated to the customer.

Start with a standard template so your users can quickly scan and grasp updates. Here's one you can use that mirrors similar traditional changelogs:

What's New

  • Feature x

  • Feature y

Improvements

  • Improvement

  • Improvement

Fixes

  • Fix

  • Fix

Write user-focused updates

Many release notes are often done last minute or written by the developer who shipped the feature through the lens of what was built instead of what it does for the end user. When this happens, release notes are filled with updates that are not helpful at best, and confusing or frustrating at worst.

That might work for you if you're a B2B SaaS product that sells a product to developers, as your users may appreciate getting very technical or very granular updates. But in general, users want to know the "so what?" behind updates.