How to Write Release Notes Engineers Are Proud of

Picture an engineer on a Friday afternoon, watching someone else write the release notes for the feature they spent six weeks building. The product manager types "Improved connection reliability" and moves on.

The engineer stares at the screen.

Six weeks. A race condition buried in the connection pool that only surfaced under specific load patterns. A complete rewrite of the retry logic. Circuit breakers added to prevent cascading failures. A tradeoff between connection timeout and throughput that took three days of benchmarking to resolve. Four words.

That's the problem with most release notes. It's not that they're too technical or too simple or aimed at the wrong audience. It's that they erase the interesting part.

What Gets Lost in Translation

The standard defense of vague release notes is that users don't care about the implementation. They care about outcomes. "Improved connection reliability" tells them what changed in terms they understand.

There's something to this. But it misses who else reads release notes.

Downstream developers integrating your API care a great deal about what changed under the hood. A change to retry behavior affects how they handle failures. A new circuit breaker pattern changes the contract they've been building against. When release notes say "improved reliability" without specifying what changed, those developers have to guess, or test, or file a support ticket. Documentation functions as a quality signal that shows the level of investment made in the developer experience of an API. Vague notes signal that nobody thought carefully about who would read them.

There's also the internal record to consider. An empirical study of open-source change logs found that between 3.7% and 78.6% of actual code changes went unrecorded in the corresponding changelog files. The work happened. The documentation didn't. Over time, that gap becomes the gap between what the codebase does and what anyone believes it does.

Engineers know this. When they watch their work get summarized into a generic phrase, they're not being precious about credit. They're watching the institutional record get corrupted.

What Engineers Actually Want to See

The Software Craftsmanship movement holds that developers should be proud of their work, and that pride comes from producing software that is well-crafted, not merely functional. Release notes are part of that record. When they flatten complexity into "bug fixes and improvements," they don't just misrepresent the work; they make it invisible.

What engineers actually want is specificity about the problem that was solved.

Not "fixed a bug in the authentication flow." Something like: "Fixed a race condition in the token refresh logic that caused intermittent 401 errors under concurrent request load. The fix adds a mutex around the refresh operation and caches the result for 30 seconds."

That note does three things. It names the problem. It explains the cause. It describes the solution in terms that let a developer understand whether the fix affects their integration.

The Google developer documentation style guide is explicit about this: use active voice, make clear who is performing the action, and don't let passive constructions obscure what actually happened. "A bug was fixed" tells you nothing. "We fixed a race condition in the token refresh logic" tells you something.

Acknowledgment of tradeoffs matters too. Engineering is almost never about finding the perfect solution; it's about finding the best available solution given the constraints. When a release note says "Migrated from synchronous to asynchronous processing for webhook delivery," a thoughtful reader wants to know what that means for ordering guarantees. A note that says "Migrated to async webhook delivery; delivery order is no longer guaranteed but throughput increased by 40%" is more honest and more useful.

Michael Nygard's original argument for Architecture Decision Records applies here: without understanding the rationale behind decisions, future developers are left with two bad options. They can blindly accept the decision, which is fine if it's still valid and dangerous if the context has changed. Or they can blindly reverse it, which may undo something that was load-bearing. Release notes are a lightweight version of that same record. They capture what changed and why, at the moment when the reasoning is still fresh.

The Blank Page Is the Real Bottleneck

The obvious solution is to have engineers write their own release notes. When they do, the notes tend to be better. They include the detail that matters to power users. They surface architectural decisions that affect integrations. They use language that signals competence rather than hedging it away.

The tradeoff is real, though. Engineers are expensive, and writing is not what most of them want to be doing on a Friday afternoon. The quality is also inconsistent. Some engineers write excellent notes; others write commit messages with extra steps.

The Keep a Changelog project has been making this argument since 2016: changelogs are for humans, not machines, and they should be curated rather than generated from raw commit logs. Commit log diffs are full of noise. Merge commits, documentation changes, typo fixes. The purpose of a changelog entry is to document the noteworthy difference, often across multiple commits, and communicate it clearly. That curation takes judgment.

This is where the blank page problem comes in. The hardest part of writing release notes isn't the writing. It's starting. An engineer who has just shipped a feature knows exactly what changed. Sitting down to translate that knowledge into structured prose is a different kind of work, and it's easy to put off.

Recent research on LLM-powered release note generation suggests a practical path forward. The SmartNote system, published at FSE 2025, aggregates changes from code, commits, and pull requests, then uses an LLM to generate structured, prioritized release notes. In evaluations, it outperformed or matched existing methods on completeness, clarity, and organization. The key insight is that the raw material for good release notes already exists in the engineering workflow. The work is in the extraction and structuring, not in the invention.

A case study from a large European bank illustrates the validation piece. Engineers were required to write detailed changelogs for every merge request. In practice, most were skipped or incomplete. They built an LLM-powered system that generated draft changelogs from the merge request content. Engineers then reviewed and approved. As engineers edited the AI-generated drafts, those revisions were used to improve future outputs. The system got better over time because it was learning from the people who actually understood the work.

That's the model that works. AI generates the first draft from the engineering artifacts. Engineers review, correct, and approve. The output reflects their work because it's built from their work, not from a product manager's interpretation of it.

Anyway. Here is a framework that captures what substantive release notes actually need.

What to include in every release note that matters:

• Problem context: What was broken, missing, or suboptimal before this change? One sentence is enough.
• Technical approach: What changed under the hood? Name the specific components, patterns, or architectural decisions involved.
• User-facing impact: What does a developer or user experience differently? Be specific about the behavior change.
• What didn't change: If something adjacent to the change might be expected to behave differently, say explicitly that it doesn't. This saves support tickets.

What to avoid:

• Hedging verbs: "may," "should," "might," "could." If the behavior changed, say it changed.
• Generic nouns: "performance," "reliability," "stability." These are not descriptions; they are categories. Describe the specific thing that improved.
• Passive constructions that hide the actor: "A bug was fixed" tells you nothing about what the bug was or how it was fixed.

The Semantic Versioning specification makes a related point about version numbers: they are a communication tool. A major version bump signals breaking changes. A minor version bump signals new backward-compatible functionality. A patch signals bug fixes. Release notes are the prose layer on top of that signal. They explain what the version number implies.

If the notes don't reflect the work, the work doesn't exist in the record. Six weeks of debugging a race condition becomes "improved connection reliability," and the next engineer who touches that code has no idea why the mutex is there.

If your engineers are writing release notes manually and hating it, or if non-technical writers are writing them and engineers are silently cringing, Doc Holiday generates structured drafts from engineering workflows that engineers can validate and ship. It's built to reflect the work, not simplify it out of existence.