Release Notes vs Changelogs

Over the past few weeks, your team put in a lot of effort. The day has finally arrived. You just launched a bunch of brand-new features that will CHANGE EVERYTHING!

Now what? Should you publish release notes to detail what has changed? Do you need to create a changelog? Which one is best for your customers, and what are the real differences?

We'll explore the differences and help you in determining if you should concentrate on release notes, a changelog, or perhaps combine the two to spread the word.

What Is a Changelog and When Should I Use It?

A changelog is a record of important updates to a product or software. It typically includes:

• Added new features.

• Changes for changes to existing features and functionality.

• Deprecated for soon-to-be removed features.

• Removed for now removed features.

• Fixed for bug fixes.

• Security to announce vulnerabilities.

A changelog's objective is to keep everyone up to date on the software's development and changes. A changelog is frequently read by developers or passionate users who demand all the information.

Let's look at how Sketch notifies its users of the new features in each update.

Sketch is a design tool, so it's critical that the changelog looks the part. The release version and download link are prominent, and the sections are easy to read, thanks to the excellent typography. Each enhancement and bug fix is described in a single sentence. Keeping it brief and simple to read.

They also make it very simple to jump to a specific release by including a dropdown in the header section (which isn't visible in the screenshot). The Sketch changelog is fantastic.

React updates are a more technical form of a changelog. React is a well-known programming library. Developers are the intended audience.

Aside from the design, it isn't that different from Sketch. To keep it succinct, individual changes are limited to a single sentence. But since this changelog was written for developers, who might want to look under the hood of the changes, every change has a link to the actual code change as well.

Note that there is no hard and fast rule about the terminology that should be used. The most important part is that it's easy to read and understand.

A fantastic resource for how to write a great changelog is:  https://keepachangelog.com.

What Are Release Notes, and What Does a Great Release Note Look Like?

Release notes are a great marketing tool to accompany a release of new features. It's your opportunity to tell a story, explain what problems you are solving and present new features in their best light. You want to get people excited!

Your customers and end-users are the target audience for release notes. Release notes show momentum and demonstrate that you continue to innovate. But they are also a great tool to get prospects over the line.

Here is an example of a major update from Webflow.

Notice the big title to exactly describe what to expect from the update? Clear and concise description and an image to visually show what has changed.

Discord is another example of well written and targeted release notes.

The fonts and styling is playful and targeted to their developer audience. The description is concise and a promotional video embedded in the announcement creates excitement. We also love the table of contents on the right for longer updates.

A few tips for writing great release notes:

1. Capture the readers attention quickly: Avoid long winded intro's that are only loosely related to the announcement.

2. Be clear and concise: Write short, simple sentences that clearly explain the changes made. Avoid using technical jargon or complex terms that might confuse your users.

3. Use headings and bullet points: Organize the changes into categories and use headings to clearly differentiate between them. Use bullet points to list individual changes.

4. Highlight important changes: Use bold text or highlight important changes so that users can quickly spot what's new.

5. Add images or videos: A picture is still worth a thousand words.

6. Add useful links: Link to in-depth blog posts or documentation for more details.

7. Keep your audience in mind: Only add updates that are relevant to your target audience.

Changelog or Release Notes… why not both?

Now, you may be asking yourself: why not just combine both changelogs and release notes into one document? After all, why should I keep two separate documents when I can have it all in one?

The answer is simple: because you can have your cake and eat it too. By combining both forms of communication into a single document, you can get the best of both worlds and give your customers the maximum amount of insight into your product.

A great example of a product that mixes release notes with a more detailed changelog is Raycast.

For each announcement, Raycast highlights one or two major features with a more detailed description and screenshots. Then below that they list improvements and bug-fixes in a concise, one sentence format that is more common in Changelogs.

If your audience is more technical or wants to know about everything that's been released, we highly recommend this approach.

Plus, released.so makes this process easy! All you have to do is connect your Jira tickets to Released, and we'll take care of the rest - our system will automatically generate beautiful release notes with changelog sections so that you don't even have to lift a finger.

Ways to distribute your announcement

If you decide to go the extra mile and create a beautiful release note, why not distribute it in style too? Don't burry your release notes in a dark corner of your website.

When done right, release notes can be invaluable content that enables you to engage with your customers across multiple channels. From emails, in-app notifications, blogs and social media - there's no shortage of ways to get your news out there.

Time to Up-Level Your Customer Communication

Improving your customer communication and engagement not only leads to happier customers, but also to better retention.

Our mission is to help teams up-level their customer communication. From planning and writing to publishing your announcements. Released takes the hassle out of product announcements.