A changelog records notable changes to your product. A public product update gives readers the context they need to understand a particular release, feature, or milestone. The same change can belong in both places.
Choose the format by asking who needs the information and what they should do with it. A customer checking whether a bug is fixed has a different question from a founder discovering your software for the first time. Both deserve a clear explanation.
What a changelog should do
A useful changelog makes product history easy to inspect. Include the date or version, the notable changes, and any action a user needs to take. Write for people who use the software, with enough detail to understand what changed.
The Keep a Changelog convention recommends a curated release history, grouped changes, visible dates, and linkable versions. It also recommends calling out deprecations and removals clearly. These are useful conventions rather than a universal format every product must follow.
For a developer tool, GitHub Releases can package a tagged version with release notes and downloadable files. A SaaS team might instead keep its record on its own website or in its documentation.
A changelog can be understandable and useful to nontechnical customers too. A raw list of commits usually needs editing before it answers their questions.
When a public product update helps
A public update is useful when a change needs a fuller explanation: who it is for, the task it helps with, what is available now, and how someone can use it. That audience can include existing customers and people who have never tried the product.
A new integration, a substantial capability, or a public beta may deserve that explanation. A small improvement can qualify too if its practical effect matters to a particular group. Technical complexity alone does not determine how much announcement copy you need.
A public update should give readers enough context to judge the change. Include availability and limitations alongside the benefit, and link to detailed instructions where they exist.
The same release, two useful explanations
Consider a fictional reporting app that adds CSV downloads and fixes a filter bug. These examples describe an invented release, not a real product or measured customer result.
Changelog entry: Added CSV downloads to saved reports. Fixed a date-filter error affecting reports that span two months.
Public update: You can now download a saved report as a CSV file and work with its rows in a spreadsheet. Open a report and choose Download CSV. The file contains the columns shown in your saved view; it does not include hidden fields.
The changelog records both changes. The public update focuses on the capability a reader may want to try. If the filter fix materially affects a customer's work, give those customers the information they need as well.
Choose a format for the change you shipped
- A routine fix: usually needs a clear changelog entry. Add a wider announcement when the impact warrants one.
- A new capability or integration: record the release details, then consider a public update explaining the task and audience.
- A change that requires user action: document the precise steps and communicate with affected users through the channels they rely on. A general public post may be useful additional context.
- A milestone: can make sense as a public update when there is meaningful progress to explain. Include a changelog entry if a software change is part of it.
These are starting points. Some teams use detailed changelog entries as their main customer announcements. The format's name matters less than whether readers can find the information and understand its relevance.
Build both from one verified set of facts
Start with a shared release record: what shipped, when it became available, who can access it, how to use it, and any limitations. Check those facts before adapting the message for different readers.
- Update the changelog or release notes with the complete, accurate record.
- Choose the change that needs a broader explanation. Give it a specific headline and explain the reader's task.
- Link the public update to the relevant release entry or documentation. Add a link back when the extra context helps.
- Keep dates, availability, and instructions consistent across both pages. Correct them if the release changes.
You can reuse the facts while adjusting the depth and emphasis. For the writing structure and a reusable template, see how to write a product update people actually read.
Give useful updates a permanent home
Publish the explanation at a stable URL you can reuse in your product, documentation, and future announcements. Link to the specific change rather than asking readers to search a long archive. Keep the underlying release information available after the initial announcement.
ShipFeed gives software products public pages with their approved updates attached, so readers can follow the product's progress. It can complement your own changelog and documentation with another public place to explain meaningful releases. Product and update submissions are reviewed.
Keep the detailed release record where your users expect it, and choose public updates that give a broader audience something useful to understand.