Definition
Release notes are entries published alongside a product release that describe, for the people who use the product, what changed. The tutorial on writing release notes and a changelog distinguishes the two words it uses: a release note is the entry written for one change, and the changelog is the page or feed that keeps every entry in date order. People often use the terms interchangeably.
A release note is documentation and marketing at once. It is the factual record that support agents, salespeople and customers' administrators search months later, and it is also the moment a customer decides whether a change deserves their attention. Notes written only as records are accurate and unread; notes written only as announcements leave out the limits and dates, and support pays for it.
What each entry states
The tutorial gives each entry a fixed order so readers learn where to look: the date the change reached customers, a label (new, improved, fixed or removed), a headline saying what the reader can now do, why it matters and for whom, how to use it, availability by plan, region, platform and role, and any action administrators must take. An internal evidence note records where the proof for any claim is kept.
Three choices separate a useful note from a ticket title. The headline is the change for the user, not the name of the component. Availability is stated precisely, because a reader who cannot find a feature the note described will contact support or decide the note is wrong. And any benefit the note claims is checked like any other marketing claim, since a release note that describes benefits is marketing communication.
Removals and changed behaviour deserve the most care. A customer who finds a button missing without warning stops trusting every other note.
In practice: support readiness and the published changelog
Release notes connect to the launch process at both ends. The product launches hub gives support the release notes, the likely questions and a route to escalate as part of support readiness, so agents never learn of a change from a customer. It also names the opposite failure: a significant capability that ships as one line in the changelog because nobody decided its tier. The product marketing hub explains the cause upstream: a launch planned before messaging exists ships whatever the engineering team wrote in the notes.
For apps, notes are part of every release's routine. The app marketing operations playbook puts release notes users read alongside a listing checked against the release and deep links tested before campaigns use them, with the notes written with the product marketer rather than left to the developers alone. The app store listing checklist starts from the release notes or ticket, so the store listing can be checked against what the app now does.
An invoicing platform rewrites its notes for the people who read them
Pittesk Invoicing Platform published notes such as "EXP-2214 CSV handler refactor" and "UI: move export to toolbar". The second of those moved the export button, and support logged 140 contacts in a fortnight from customers who could not find it. The product marketer rewrote the format: each entry now opens with what the customer can do, states who has the change and from which date, and links the help article. The export entry was republished as "Export your invoices from the toolbar on any list page. Available on all plans from 9 June; the old menu option has been removed", linked from the export help article and sent to support with a suggested reply. Contacts about the export button fell to 31 in the following fortnight, and agents answered most of them by linking the note.
Related terms
A Change LogA dated record of changes made to tracking, accounts, reports, lists or rules, with who made each and why, so later movements in the figures can be traced. in this glossary's sense is an internal, dated record of changes to tracking, CRM fields or reporting, kept to explain data later; the public product changelog shares the idea of a dated record but is written for customers. A change still in a Beta ProgrammeSelected customers use a working product or feature before general release, so the business learns whether it works for them and what the launch needs. is in early access, so its note says so and is updated when the change reaches everyone. And a Go-to-Market StrategyThe plan for how a product or offer reaches and wins its target customers. plan covers the releases big enough to need more than a note, where the note becomes one asset among many.
Common confusions
- Release notes are for engineers. They are for the people who use the product. An internal engineering log can stay internal.
- Only new features need a note. Fixes, changed behaviour and removals are the entries customers most need, because an unexplained change creates support questions.
- The note is dated when the work was done. It is dated when the change reached customers.
- A digest email can go to everyone who uses the product. A round-up encouraging use of new features is promotional and goes only to people who agreed to receive it.
- A wrong note should be deleted. It is corrected in the open with a dated line, because the changelog's value is that it is complete.
