Changelogs as a Source of Truth for Product Facts
Maintenance · 9 min read ·
A dated changelog keeps specs, claims and listings accurate. How to write entries people trust, what to include, and how to link them to your fact sheet.
Most product facts go out of date because nobody notices that something changed. A feature is added; the fact sheet still says it is planned. A limit is raised; the documentation shows the old number. An integration is retired; the listing still mentions it. The product moves, and every page that describes it lags behind.
A changelog is the cure. Used well, it is not just a record for customers but the working source from which other pages are corrected. This guide explains what a changelog should contain, how to write entries that readers trust, and how to wire the changelog into the rest of your published facts so that nothing falls silently out of date.
What a changelog is for
A changelog has three audiences, each with a different need.
Customers want to know what is new, what has changed in the way they use the product and what has gone. They read to decide whether to adopt a new feature or adjust a workflow.
Integrators and technical buyers want to know about changes to interfaces, limits and behaviour that could break something. They read to protect their own systems.
Reviewers, comparison writers and assistants want a dated trail to confirm that a claim was true at a given time. They read to decide whether a statement about your product is current.
A changelog that serves all three is chronological, dated, specific and written in plain language. It does not hide behind internal codenames and does not read like a marketing newsletter.
The anatomy of a good entry
Every entry has the same few parts.
- Date. The day the change reached customers, in an unambiguous format.
- Title. A short, factual description: "Export now includes custom fields."
- Category. A small label from a fixed set: added, changed, fixed, removed, security, deprecated.
- Description. One to three sentences saying what changed and who it affects.
- Impact. Whether action is needed. "No action required" is itself useful.
- Link. To documentation, a how-to or the relevant fact sheet row.
Keep the label set small and use it consistently. Readers learn to scan for "removed" and "security" first, so those labels must be reliable.
Software versioning is the practice of assigning unique identifiers to states of a piece of software. If your product exposes a versioned interface, give each entry the version it applies to. If it does not, dates alone are enough; do not invent version numbers for the sake of appearing rigorous.
Writing for the reader, not the repository
The commonest failure is copying commit messages. "Refactor export service to use batch writer" is accurate and meaningless to a customer. A reader-oriented version reads: "Large exports now complete faster. No action needed."
A few habits help.
- Lead with the effect on the user. What can they now do, or what will behave differently?
- Name things the way the interface names them. Use the labels customers see.
- Be specific about scope. "Available on all plans" or "Only on plans with this feature."
- State removals bluntly. "Removed: the legacy import format. Use the new format; see the guide."
- Keep security entries factual. Say what was fixed and whether customers need to act, without exaggerating or minimising.
- Do not edit the past quietly. If an entry was wrong, add a correction with its own date.
Google's guidance on creating helpful content stresses that readers should be able to see how a page's author knows what they say, and that content should be updated when it becomes inaccurate. A dated changelog gives a reader exactly that: evidence of when each statement became true.
Breaking changes deserve special care
A breaking change is one that can cause an existing customer's setup to stop working. Treat these as a separate class.
- Announce early. List the change as deprecated first, with a date for removal.
- Provide a path. Say what to do instead and link to instructions.
- Show it everywhere. Put the notice in the changelog, the documentation, the interface responses where relevant and an email to affected accounts.
- Remove on the stated day, not earlier. Delaying is acceptable; surprising people is not.
- Record the removal. When the day arrives, add the "removed" entry and update every page that mentioned the old behaviour.
Those last two steps matter most for fact accuracy. The removal entry is the trigger to correct the fact sheet, the integration table and any listing text that describes the old behaviour.
Connecting the changelog to your other pages
Here is the practical bit. Decide that every changelog entry has a "facts affected" field, even if it is not shown publicly. When an entry is written, the author lists which published facts it touches:
- A new integration: the integrations table and the listing description.
- A raised limit: the limits table.
- A new compliance report: the security page.
- A pricing model change: the pricing page and fact sheet.
- A removed feature: everything that mentioned it.
The release is not finished until those pages are updated. Make it part of the checklist, owned by the person who ships the change. It is a small amount of discipline that prevents most stale-fact problems.
For structured data on your pages, remember that the markup should reflect what is visible on the page. Schema.org's SoftwareApplication type includes a version property and a release notes property, among others. If you use them, update them in the same step as the visible text so the two never disagree.
Handling frequency
How often should you publish? There is no single answer, but a few principles hold.
Publish when it ships. A changelog written a month later is a history, not a changelog.
Batch small fixes. A weekly or per-release roundup of minor fixes is fine, as long as notable changes get their own entries.
Do not pad. A long list of trivial entries makes real changes harder to see.
Do not go silent. A changelog whose latest entry is a year old signals either an abandoned product or a neglected page. If a quiet year was genuine, a short entry stating that the product is in maintenance mode, if true, is more honest than an empty page.
Using the changelog to answer buyer questions
A well-kept changelog answers questions that buyers otherwise ask by email.
- "How actively is this product developed?" The cadence of entries shows it.
- "When was this feature added?" The date is there.
- "Has security been handled?" Security entries show a record.
- "Is the interface stable?" The ratio of breaking changes to additions shows it.
Point to the changelog from the fact sheet in the history block, and from any directory listing that has a field for it. When a reviewer wants to check a statement about your product, they should land on a page that can settle the matter.
Review, ownership and tooling
Decide who owns the changelog. In a small team it is the person who ships the release; in a larger one, a product or documentation lead. The owner's job is to review every entry for clarity before it goes live.
Tooling can help without replacing judgement. Some teams draft entries from tagged commits or from pull request titles, then edit by hand. Others keep the changelog as a plain text file in the repository so that changes are reviewed like code. Whichever you choose, keep the published version simple: one page, newest first, with stable links to each entry so that other pages can point to a specific change.
Once a quarter, read the changelog end to end. Check that each removal has propagated and each addition appears in the fact sheet. This audit takes an hour and catches the drift that daily work misses.
A short template
- Date: a clear date.
- Category: added, changed, fixed, removed, security or deprecated.
- Title: what changed, in the user's words.
- What it means: who is affected and what, if anything, they need to do.
- Facts updated: internal note listing the pages touched.
- Link: to the relevant documentation.
An example of a changelog entry doing its job
Consider a small product that stops supporting an old file format. The entry reads: "Removed: import of the legacy file format. Files in this format can no longer be uploaded. Convert them with the converter in settings, or export again from the original tool. Deprecated since the previous quarter; see the migration guide."
Five things follow from that single entry. The import documentation drops the legacy format. The fact sheet's list of supported formats is corrected. The integration table's row for the tool that produced those files gets a note. The listing description, which once mentioned broad format support, is trimmed. And the support team has a link to paste into replies. The entry did more than inform customers; it set off four corrections that would otherwise have been forgotten.
Questions teams ask about changelogs
Should we publish negative news? Yes, when it affects users. Removals, security fixes and known issues belong in the record. Readers trust a changelog that includes inconvenient entries more than one that includes only good news.
What about unreleased work? Keep it in a roadmap, clearly separated, and avoid dates you cannot guarantee. The changelog records what has happened, not what is hoped for.
How far back should it go? Keep the whole history available. Old entries help reviewers verify older claims and help customers who upgrade after a long gap. If the page grows long, paginate by year rather than deleting.
Who is allowed to edit? Anyone on the team may propose an entry; one person approves. A changelog with many authors and no editor drifts in tone and quality, and tone is part of how readers judge whether it can be trusted.
Summary
A changelog is more than a courtesy to customers: it is the source from which your other published facts are corrected. Write dated, specific, plain entries; treat breaking changes as a separate class with early notice; record the pages each change affects and update them as part of shipping. A product whose changelog is current is a product whose fact sheet, limits table and listings can be trusted too.
Questions and answers
- What is a changelog?
- A dated, human-readable record of notable changes to a product: additions, changes, fixes, removals and security updates.
- How is a changelog different from release notes?
- Release notes usually describe one release for a specific audience. A changelog is the cumulative, chronological record across releases.
- Should every change be listed?
- Every change that a user, integrator or buyer could notice should be listed. Internal refactoring generally should not.
- Can a changelog be generated automatically?
- Tools can draft entries from commit messages, but a person should edit them, because raw commit messages are written for developers rather than readers.