A Theory of Release Notes

They’re dry, confusing, and a general waste of time to read. Only the really die-hard users and developers even have a use for them. Right?

That’s the stereotype, and it’s the primary reason for the stigma against them. Of course there’s a kernel of truth in that: a lot of people don’t read release notes, but some people rely on them.

Those people generally do not have a lot of time– they need to find the information they’re looking for, fast, but there may also be important updates that they didn’t anticipate, and might not notice if those are not brought to their attention.

At the same time, if you write release notes specifically for that audience, who tend to be very technical, perpetuates the stereotype. If you make release notes seem irrelevant for most people to read, most people will regard them– rightly– as irrelevant. But that’s a misrepresentation of what release notes are supposed to do.

The reality is that release notes are intended to document improvements impact the users’ experience for the better. Users may or may not want to learn about these, but the writer’s job is to make it as easy as possible for them to do so.

Hold up- what even are release notes?

The minimum basic requirement of a document to makes it release notes is that…they’re associated with a release. That’s it. It sounds obvious, but often there’s a bunch of stuff in release notes that just doesn’t belong there.

There is, for example, a temptation to include content that isn’t release notes. Down that path lies peril– the notes may wander into flowery prose about how great the product is, or some other form of marketing-speak. When this happens, not only are potential clients unlikely to find information they’re interested in, but for existing users (who don’t need to be sold on a product they’ve already bought/licensed) that content may bury the updates they’re actually looking for, counterproductively making them harder to find.

In the opposite direction, a few short boilerplate/ambiguous notes without substance are also counterproductive. Once you make the effort to read the notes for a release and they’re totally generic, what’s the incentive for you to ever do so again?

Release notes, when they’re created thoughtfully and collaboratively, can achieve multiple goals:

• Announce continuing iterative improvements that a company is making to its products for the benefit of users.
• Provide a means by which developers, and product teams generally, can communicate with users about what they’re doing.
• Give users the opportunity to learn about those changes when they happen.

But release notes are like pizza, right? Even when they’re bad, they’re still good?

Nope.

Even with bona fide release notes there are numerous potential pitfalls in designing them, including:

• Updates/bug fixes are included in the release notes that really shouldn’t be, for various reasons such as if the notes are already long/numerous enough and users don’t need to read every back end update for changes they’ll (most likely) never see.
• An “upcoming features” section over-anticipates features to be released in the future, promising something that won’t be delivered.
• The author(s) of the release notes includes inaccurate information that isn’t caught before the notes are deployed.
• The author fails to include information that is urgent/critical for users to see.

In that latter case it may be a good idea to not include the important update in the release notes. Maybe instead, you splash it across the top of some screen where users will see it, such as the product help site or in the navigation of the product itself. There’s also no law (to my knowledge) against putting that information in both locations, so long as no update text contradicts the text in some other location. But– critically– these choices must be deliberate, strategic decisions.

There’s also the matter of different degrees of expertise. An update could be highly relevant for users, but described using highly technical language they can’t understand. This contributes to that stigma of impenetrability.

Worse– what if the translator isn’t exactly fluent in the language they’re translating, and gets it wrong? What if the writer is twisting in the wind to meet a deadline, just trying to get something down on “paper” because they have to do it now? Misrepresentation of enhancements in release notes is is a concern for users, developers, and writers alike.

There are multiple potential causal factors there, but pinning down someone to blame isn’t nearly as urgent as figuring out how to get accurate information in front of the eyeballs of users, in a way that they find accessible and advantageous for their needs.

Let’s look at some hypothetical release notes as an example:

---

It’s easy to see the difference in an example like this, isn’t it?

With the second set of release notes, it’s hard to know where to start. Users don’t usually know, or care to know, the names of algorithms used in a product. Anyone who cares about the motivations of the founders should be looking at the “About” section on the website, because those aren’t a new development that belongs here. The two bug fixes amount to a severe overshare that might even be used against the company in court (!), and a problem that’s only partially comprehensible and only partially fixed.

That’s so complicated! Isn’t there an easier way?

Yes, there’s a simple solution, and three out of four writers endorse it!¹

Okay, it’s actually not that simple. It requires buy-in from the product teams building the features and solving the bugs that are the reason for the release notes in the first place. That’s the not-so-simple part. But when the product teams are invested in creating the best possible release notes to complement the features they’re building and bugs they’re fixing, a writer can collaborate with them to ultimately create the highest quality release notes.

A writer embedded in the product team who takes part in their scrum meetings, post mortems, etc., gains a huge advantage when it comes to release notes. In that situation Nicole, who designed the new feature, can sit down with Janet, the writer, and walk through what changed. Janet can then translate that information into language that makes sense for users– even using language that “sells” a new feature product teams are excited about, passing along that enthusiasm to the people reading about it.

Another advantage is when the product team feels comfortable writing draft release notes themselves, based on user stories. For example, the Bravo Notes add-on for Azure DevOps can be used to set up a template that automatically routes release note content from user stories into a release notes template, with settings that predetermine where each update or fix belongs. That approach allows product teams to author release notes directly, albeit as raw text that requires editing and formatting before they can be published. The biggest benefit there is that a preliminary set of release notes can be created via a query, directly pulling content from user stories selected for the release notes based on prior agreement amongst the team in collaboration with the writer.

Even in the absence of these beneficial arrangements, the writer and product team must still maintain a regular line of communication that follows the release schedule, and can be adjusted to accommodate busy periods for both product teams and writers.

Why is it so important for internal teams to c-o-m-m-u-n-i-c-a-t-e about release notes?

When the product teams aren’t already sold on the importance of release notes, that can cause writers to shoulder most or all of the responsibility for creating them. This hamstrings both the writers and the content they create, resulting in communication with users that mirrors the quality of communication between teams — as in, not good.

What audience(s) are you catering to? What’s their level of knowledge about, and/or familiarity with, the subject matter? This is standard tech writing stuff, but the “curse of knowledge” kicks in hardcore when devs are describing their work to writers, who are, in turn describing it to users. The curse of knowledge, or curse of expertise, is a cognitive bias that causes a person to overestimate the level of knowledge held by their audience, resulting in a tendency to speak over their heads and thereby fail to achieve mutual understanding.

Much as we might agree that anyone who truly grasps a subject should be able to explain it in accessible terms, in the real world this is often not the case. Or at least, the real world often requires an interpreter. That’s where a writer’s renaissance-like aptitude for explaining anything to anyone comes into play.

Again, this is where being part of an Agile team can be enormously helpful– development teams explain what they’re doing for each other on a regular basis. They may do a presentation for other teams prior to the release to show off their updates, but that’s long past when the notes needed to be compiled (generally speaking). So after a dev walks through a new feature with a writer, the next step is for the writer to imagine what the final (for this iteration, at least) product will look like with enough certainty and information to represent it for users in the release notes.

For writers who aren’t part of an Agile team, creating good release notes might require more proactive effort toward collaboration, as well as a little sleuthing to locate enough information about each update to determine which ones belong in the release notes, and what to say about them.

So are release note authors embedded journalists, or private investigators, or diplomats?

Answer: D. Yes, all of the above.

The challenge for the writer in all of this is that they can neither write from the bottom up, nor the top down. Users in the target audience for release notes don’t benefit from reading about everything each developer did to make a change, and they equally don’t benefit from reading an “About” page worth of summary of who the company is, what solutions it offers, its vision and mission statement, etc. before getting to any actual updates.

That’s all useful information, but not here. Here, it actually gets in the way.

This can result, unfortunately, in having to reject some contributions from both devs and product owners/managers. It may mean emphasizing certain updates more or less than product teams believe they deserve, or structuring the release notes according to a format designed by the writer team, which applies across the product suite or platform regardless of whether one product team would prefer that things worked/looked differently. That is to say, an individual product isn’t an island– writers working with them must emphasize the need for consistency in voice, as they do with other products.

The potential for conflict here is inevitable, but it can be resolved smoothly by writers and product teams who communicate often, and are respectful of each other’s work, in recognition of their respective contributions to the project. That relationship creates trust and reassurance that nobody’s vision is overlooked.

The relationship between the author of release notes and the product team(s) they’re working with can vary wildly, and the quality of the release notes depends on this relationship. A writer who isn’t given meaningful access to a product team, regardless of the reasoning for this, must do the best they can with the hand they’ve been dealt.

Here are some overall good strategies for building release notes that can be applied to a greater or lesser extent, depending on that relationship.

• Learn about the changes to be included in the next release ASAP. Obtain a list of them, or create a list yourself to evaluate which ones belong in the release notes. Create and/or review that list along with the product team.
• Find out what features the product team are excited about, and why. What do they consider an accomplishment? What are they eager to deliver for users? Don’t be afraid to brag about these changes in the release notes, so long as you’re not too flowery and the updates are of interest to users. If appropriate, put these changes in a highlights section at top, or other place where users are most likely to see them.
• Contextualize the update— is it part of a larger collection or sequence of changes? Can you say that the next step in implementing [feature] has arrived? Is it something users have been actively requesting, so you can proudly announce that the change they’ve clamored for is now available? If it’s a bug fix, what’s the best way to describe that.
• Keep brevity in mind without short-changing your own updates by leaving out important details.
• Keep updates that aren’t ready to be included in this release’s notes on your radar. Think about how they should be described in advance, so that you already have ideas in mind for the next release.
• Remember your role in this process. You are not required to be an SME, though you might become one over time. Your job is to alert users to important changes to the product(s) they’re using in terms they can understand. This may require communicating with users themselves to discover what their priorities are. You’re writing for a specific audience, and their feedback is invaluable.

Do not take these suggestions as implying that the responsibility for creating good release notes rests entirely on the writer. Release notes are an inter-team project, and the healthiest work environment is one where product teams recognize this and they collaborate with writers to create the best release notes possible.

At the same time, if the writer is working with a team of other writers, they will have their own intra-team standards for how release notes are structured– and possibly other standards, such as when release notes are compiled, what form the output should take, and where the notes should be shared to reach their audience. These requirements may supersede the wishes of a product team, as mentioned above, and they may even supersede the preferences of the writer in some respects.

The writer should communicate those standards to the product team and determine the best way to structure their release notes according to those standards. The writer can then also pass along the product team’s feedback to the other writers, maintaining a transparent stream of communication that also gives each respective team a view on each other’s workload, and other deadlines that could impact the release notes process.

What do good release notes look like?

It’s important to create a content voice that reflects your organization’s identity and values, and that should be as apparent in release notes as it is anywhere else. Some release notes are friendly and jocular, even poking fun at themselves, whereas others are precise and serious. Regardless, their purpose remains the same, and so (more or less) does their structure– because the fundamental constraint on release notes is, naturally, looking like release notes. That’s a standard set by a combination of tradition and informal consensus extending far beyond one company’s practices.

Good release notes are easy for a user to find, but they’re not in your face when you’re not interested in reading them. They are straightforward, brief, accurate, accessible, and– most importantly– current. Seems obvious, but it can be easy to forget amidst the internal discussions and occasional disputes concerning who should be hearing what and when, why, and how.

Release notes are part of the user experience, but they also represent how that experience changes over time. They describe growth, deliberately cultivated by people who care about making the product better– and better, and better, and better.

Help files provide information about the product and instructions on how to use it. Marketing communication shows how the product is a solution that fits the needs of potential clients. Release notes, by contrast, show progress. Release content builds on itself– it’s never the same. It tells users about the latest ideas to come to fruition, and the latest problems solved.

“Extra extra, read all about it!” your release notes might say in the introduction. “The stories you want to read about, right here!”

…Well, okay, maybe not. But you get the idea, right?

---

1. The fourth one retires next week and doesn’t give a damn. ↩︎