This page is totally under construction!

The following information been adapted with permission from an article by appcues.com (cited below).

What are release notes?

Release notes are brief documents that explain what about a software {hardware?} product has changed: what has been added, what has been removed, what has been fixed, what has been improved. They can be shipped with the product in several ways: as an appendixin other user documen tation, as a web page online, as a separate hardcopy document.

Traditionally, release notes were ignored because they were highly technical and thus unreadable by ordinary users. But, as you can see from the titles in Related Information below, there is a desire to make release notes accessible to ordinary users—not just the developers.

Note: A changelog is an archive of all the individual release notes for a product over time in reverse chronological order. See further details and examples below.

According to appercues.com, there are these tyoes of release notes:

  • Major release notes: New features, significant UI changes, new capabilities. These deserve fuller treatment with visuals, context on why the change was made, and clear guidance on how to use it.
  • Minor update notes: Incremental improvements, small UX changes. Shorter format works here, typically one to three lines per item.
  • Bug fix notes: Resolved issues. List format, plain language, with a focus on what the user experienced before versus what happens now.
  • Security patch notes: Brief and factual. Prioritize what was vulnerable and what was fixed without technical detail that creates confusion.

—https://www.appcues.com/blog/release-notes-examples

In addition, appercues lists these contents to include in release notes:

  • Header line: Product name, version number or date, and environment if relevant (web, iOS, API, etc.).
  • Summary of changes: One or two sentences framing what this release addresses and who it affects. This is the part users read first, so make it count.
  • New features: Named, with brief user impact. Lead with what the user can now do, not the technical implementation.
  • Improvements: What changed from the user's perspective. "Search results now load 40% faster" is better than "Optimized search indexing pipeline."
  • Bug fixes: Plain-language description of what the user experienced before and what happens now. "The dashboard no longer freezes when filtering by date range" tells the user exactly what was wrong and that it's fixed.
  • Known issues or limitations: If something isn't fully resolved, say so. Users respect transparency more than they resent imperfection.
  • Where to get help: A link to your help docs, support contact, or community forum. Don't make users search for where to go if they have questions.

—https://www.appcues.com/blog/release-notes-examples

Interestingly, appercues mentions that over 50% of companies launch quarterly, with 2 to 4 launches a year. 43% of companies launch quarterly for releases that have new features. And a startling 34.5% launch up to 12 times a year. (A launch is an announcement that a product or feature is available to consumers.) What appercues doesn't mention is the all these launches indicate software products are constantly changing.

What are changelogs?

As menioned above, chanelogs are ongoing compilations of release notes. Here's a example:

Example: Changelog, SharePoint Framework

Notice in this example links to the individual release notes are available in the left panel.

Writing good release notes

The advice for writing good release notes—readable even by ordinary users of the product—is the same as technical writing the world over

Changelog example

Snagit changelog (opens in a popup) illustrates several useful characteristics:

  • The title Snagit Windows 2026 Version History. That works as an indication that this is a changelog.
  • Each segment is a separate set of release notes entitled, for example, What's New in 2026.4.0 (6 October 2026)—a friendly indicator of release notes.
  • The body of each set of release notes loosely follows the pattern recommended by appercues.com:

    • New features
    Feature updates
    Performance enhancements
    Updates for IT administrators
    Bug fixes

  • The language throughout is reasonably understandable, except for the IT section which is nicely isolated.

Related information

Amazing how much attention has been paid to writing release notes. The most recent trend is to AI to draft them for you.

13 release notes examples (and what makes them work). appcues.com
Release notes. Wikipedia
How to Build an AI Agent to Automate Release Notes. Zhen Flow.
7 Best Release Notes Examples to Learn From. releasepad.io
The Life-Changing Magic of Writing Release Notes Medium.
6 Outstanding Release Notes Examples (And How to Use Each). archbee.com
How to Write Release Notes Your Users Will Actually Read. ProductPlan
The Strange Art of Writing App Release Notes . IEEE Spectrum
How to Write (Better) Release Notes in 7 Steps . SitePoint
Writing Better Release Notes. Sparkbox
What's your process for writing release notes?. Roadmap.com
Release Notes | How to write Release Notes for Software Projects. klariti.com
App Release Notes Are Getting Stupid. TechCrunch
Release notes | Google Developer Documentation Style Guide ... Release Notes
Espanso Edit changelog

I would appreciate your thoughts, reactions, criticism regarding this chapter: your response—David McMurrey.