Learning to love release notes - Anne Edwards

Release notes may look like a routine chore, but they’re often where technical teams accidentally hide the most important information: what changed for users and why it matters. Anne Edwards, a tech writer at London startup Improbable (spatial OS), argues that better release notes don’t come from being funnier or more clever—they come from being accurate, clear, concise, and explicitly user-focused. Her core message is that a lightweight style guide can turn frantic, developer-written updates into documentation readers can actually use.

Edwards starts with a practical definition: release notes are bullet-point summaries alongside a software release, typically grouped into bug fixes, new features, and known issues. She describes the common reality—release notes assembled at the last minute, with limited space and constant context switching across the whole product. To illustrate how much meaning can survive without technical detail, she recounts translating real release notes into Haiku form (5-7-5 syllables). Stripped of specifics, the lines still captured the “essence” of the change, teaching her that patterns matter more than exhaustive technical reporting.

That lesson becomes urgent in her current role, where developers at Improbable often draft release notes as subject-matter experts. The problem isn’t correctness; it’s usability. Developer-authored notes can be hard for users to interpret because they describe code changes without spelling out user impact, rely on internal context, or start with vague phrasing like “fixed a bug where…” that forces readers to do the work of figuring out what they should care about. Edwards also highlights a recurring stylistic mismatch: developers may write in the tone of standups or commit messages, while users need plain-language outcomes.

To fix this, she describes an iterative editing workflow. When a release note didn’t make sense, she asked the developer to expand it into a clearer “if/then” structure (e.g., “when X happens, Y occurs”). The expanded version gave her enough context to shorten it into a user-facing bullet. She also rewrites overly formal, abstract language (“it is now possible to…”) into direct instructions (“you can now…”), and she replaces code-centric statements with concrete user consequences (for example, clarifying how many users can connect to a deployment).

Edwards then turns to what she couldn’t find online: guidance on avoiding trendy but risky release-note styles. She critiques humorous, idiom-heavy formats as potentially wordy, obscuring the main message, and creating comprehension barriers—especially for non-native English readers. Instead, she lays out principles for a company style guide: release notes should be accurate, clear, and concise (in that order), user-focused, and supported with enough context to identify affected scenarios. She also recommends structural conventions like grouping fixes under a “Fixes” heading rather than starting every entry with “fixed a bug where…”.

Her writing tips center on “expand and simplify,” imagining the reader’s questions (“why would I want this?”), and using templates to reduce cognitive load and improve consistency. She offers three reusable sentence patterns—“You can now…”, “X now/no longer does Y…”, and “X now/no longer does Y… so you no longer/now need to Z”—as building blocks for bug fixes, features, and workflow changes. The takeaway is pragmatic: guidelines aren’t rules, but a style guide can make both authors and readers faster, clearer, and less frustrated.