Describe the change as the user will meet it
Name the screen, the button or the result the person will notice. Module names and refactors belong in a linked technical note, and only if anyone needs them.
Technical & ProductContent Creator
Release notes: tell users what changed and what to do next
Release notes list what changed in a product version, grouped by what users will notice, with breaking changes and required actions placed first. Each entry needs a version number, a date and a plain sentence a customer can act on without reading the commit history. Keep each release on its own dated page or file, so people who missed one can still find it.
What people search
Release notes: 4,400 average monthly searches.Google Ads Keyword Planner · 2026-10-09 · United States
Interest in release notes peaks in the week of June 7, 2026, and is lowest in the weeks of October 12 and October 19, 2025, and again in the weeks of August 23 and September 27, 2026.Google Trends · 2026-10-09 · United States
Section outline
The order of sections for one release
Header
The product name, the version number, the release date and a one-line summary of the most important change. A reader who stops here should know whether the release affects them.
60 wordsAction required
Breaking changes, removed features and steps an administrator must take before upgrading. When this section is not empty, it goes above every other section.
100 wordsNew
Features users can now use. Name each one the way the interface names it, and say where to find it.
120 wordsImproved and fixed
Changes to behavior that already existed. Describe what the user saw before and what they see now, not the internal cause.
120 wordsKnown issues
Problems you have confirmed and have not fixed, with a workaround where one exists. Remove an item only when its fix has shipped.
70 words
Total: 470 words
Example excerpt
Worked example: one release entry
Sample section
Illustrative example. The product, its version and its features are fictional. Marlow Shelf 3.4, released October 14, 2026 Summary: stock counts can now be recorded offline and sent when the device reconnects. Action required Administrators who use the legacy CSV import must choose a column layout before upgrading. Imports that use the old layout stop working in version 3.4 and show an error on the first run. New Offline counting. On a phone, open Count and choose Start offline session. Counts are saved on the device and sent when a connection returns. Session totals appear on the Counts screen. Improved Low-stock alerts show the supplier's lead time beside the product name, so a buyer can decide whether to reorder that day. Fixed Scanning the same barcode twice within five seconds no longer adds a duplicate line. Known issues Offline sessions cannot yet be merged across devices. Count each location on one device until the fix ships.
Format notes
Format each entry for a skimming reader
Put the version and date on every entry
A release without a date cannot be placed against a bug report or a support call. Use the version number the software displays, and write the date the same way on every page you publish.
Sort entries by what the reader must do
Readers scan for the section that applies to them. Keep the same four headings from one release to the next, so a regular reader knows where to look before they read.
Give each version its own file
Create one page or downloaded HTML file per version and name it with the product, version and date, for example marlow-shelf-3.4-2026-10-14.html. An archive of named files stays readable years later.
Mistakes to avoid
Mistakes that make release notes useless
Pasting commit messages
Commit messages describe code for developers. Rewrite each one as a sentence about the product, and drop changes no user would notice, such as a dependency update with no visible effect.
Burying the breaking change
A required migration placed under a bug fix is easy to miss. Move every change that stops an existing setup from working into the action required section, even when the release is mostly improvements.
Writing 'various improvements and fixes'
That phrase tells a reader nothing and hides the change they were waiting for. Name the change, or leave the line out.
Leaving out known issues
A reader who hits a problem with no note in the release assumes something new broke. A short list of confirmed issues with workarounds stops that guess.
Frequently asked questions
What is the difference between release notes and a changelog?
Release notes are written for the people who use or buy the product. They say what changed in plain words and what action, if any, the reader must take. A changelog is usually a longer, more technical record of every change, often kept beside the code. Many teams publish release notes for users and keep the changelog for developers.
Is there a release notes template I can copy?
The section order in this guide works as one. Copy the headings, write the action required section first, and fill the rest with entries a user would recognize. Leave out any heading with nothing under it rather than keeping an empty one.
How often should I publish release notes?
Publish whenever a version a user can install or see changes, rather than on a fixed calendar. Link the newest page from the product's update screen or help center, so people find it where they already look. A small release with one change still gets its own dated entry.
Can people follow release notes by RSS?
No. Attain OS Content Creator makes a standalone HTML page with a link you share, so no feed updates itself. Post each new link where your users already look, such as an email or an in-app notice, and state which version the page covers.
Browse by category
More references in Technical & Product
References
Onboarding Guide
References
Knowledge Base
References
Tutorial Page
References
Code Snippet Library
References
API Documentation
Reports
UX Case Study
How to build it
Follow the eight-step wizard: type, assets and description, images, branding, contact and call to action, Atty Suggestions, blueprint, and generate. Atty generates one HTML page in the background. Review it, then publish and share the page link or download the HTML file.
