Guide
Most products have more than one type of reader. A developer integrating your API reads your changelog differently than an end user checking what's new, who reads it differently than a manager deciding whether to upgrade the team's plan.
The mistake most teams make is writing for one imaginary reader — usually themselves — and hoping it lands for everyone else. It doesn't. The answer isn't to pick one audience and accept the loss. It's to understand who your readers are and write accordingly.
Before you write a single entry, know who's going to read it. Most products fall into one of three audience shapes:
Single primary audience
A developer tool used exclusively by engineers, or a consumer app used exclusively by individuals. Writing is straightforward — one voice, one level of technical depth.
Mixed technical and non-technical
A SaaS product used by both developers (who integrate it) and business users (who use the interface). This is the most common and the most challenging.
Layered audiences
Enterprise products where end users, IT administrators, and executives all have a stake in what changes. Each group cares about different things.
Knowing your shape determines your strategy.
End users care about outcomes, not mechanisms. They want to know: does this make my work easier, faster, or less frustrating? They don't want version numbers or technical architecture. They want to understand the change in terms of their own workflow.
Write for them by
Example
Smarter search
Search now understands partial words and common typos, so you're more likely to find what you're looking for on the first try. No more needing to remember the exact phrase.
Developers care about precision. They need to know exactly what changed, whether it affects their integration, and what — if anything — they need to do about it. Vague entries frustrate them. “Improved API performance” tells a developer nothing useful. “Reduced median response time on /events from 420ms to 95ms” tells them exactly what changed and whether it matters.
Write for them by
Example
/reports endpoint now supports cursor-based pagination
The /reports endpoint now accepts cursor and limit parameters for paginating large result sets. Offset-based pagination (page and per_page) continues to work — no changes required. Cursor-based pagination is recommended for datasets over 10,000 records.
Executives, managers, and buyers rarely read changelogs directly — but they do read release summaries, account emails, and in-app notifications. When they do engage, they care about value, risk, and reliability. They want to know: is this product getting better? Is there anything I need to be aware of?
Write for them by
Example
Audit logs now available on all Business plans
Every action taken in your account — logins, exports, permission changes — is now logged and exportable for compliance purposes. Audit logs are available to account owners and admins under Settings → Security.
When you have more than one reader type, you have three options:
A single entry that leads with the user benefit and adds technical detail below for those who need it. Works well when both audiences read the same changelog. The non-technical reader gets what they need from the headline and first sentence. The technical reader keeps reading.
# Structure
[Plain-language headline and benefit — readable by anyone]
[One or two sentences of detail for technical users]
[Link to docs for anyone who needs to go deeper]
Label entries by type — “New feature”, “API change”, “Bug fix”, “Admin” — so different readers can filter to what's relevant to them.
Watch out for
Tags only help if applied consistently. Inconsistent tagging is worse than no tagging — it trains readers not to trust the system.
A user-facing changelog and a developer changelog published separately. This is the cleanest solution when the two audiences have genuinely different needs and reading habits.
Watch out for
The maintenance cost — every relevant change needs to be written twice. Only worth the overhead when the audiences are large enough and distinct enough that a layered entry genuinely fails both of them.
Lead with impact, not mechanism
What changed for the reader — not how you built it.
Be specific
Vague entries fail every audience. Precision serves all of them.
State what action is required
If the reader needs to do something, say so clearly and early.
Stay consistent
Switching voice or depth between entries — even for the same audience — erodes trust.
Before publishing, ask:
Do you know who the primary reader of this entry is?
Is the opening sentence written for that reader — not for your team?
If the entry serves multiple audiences, does it lead with plain language before adding technical detail?
Is any required action stated clearly and early?
Is the tone and depth consistent with your other entries for this audience?