Everything I know about release notes. Part 1.

I’ve been writing release notes this week. This is a new thing for my company, so I get to decide what they include and what they look like. I’ve written release notes many times before, for different companies with different requirements and styles. I’ve filtered all of those styles into what I think of as a “general” style for release notes, which is my go-to style: short, uncluttered, let the reader get the info as quickly as possible.

But let’s see how that idea holds up once I start analyzing it.

Release notes have a simple purpose

Because my current company releases regular updates, I’m going with a fairly minimalist style that allows me to write and edit them with minimal amount of work. For these small releases, I’m going with short descriptions, no screenshots, and no fancy layout or formatting.

I write the release notes first, and then work on updating the documentation. Online release notes must include links to the documentation that describes the feature and/or workflow; that topic should include expanded descriptions, screenshots, videos, and whatever else is needed to show the value of the feature, how to use it, and even just where to find the new thing.

So for new feature descriptions in the release notes I’m concerned with a short explanation, including information about why this new/improved feature is awesome and useful and why the reader cares.

And that information comes from…

The “why do I care?” information is the business case, and probably comes from product management. The engineers may or may not have that information; in my case, we don’t have a PM team, so I talk to the engineers who wrote the code and the people who requested it. If a customer requested it, that request came through one of the teams that work directly with customers (data scientists or sales engineering) or through customer support. And since I’m the support team, I really hope that I captured that information when I was talking to the customer!

At times, the tech writer is the link between engineering and the internal requestor: We meet with the requestor (or PM) to learn the Why, and with engineering to learn the How. And if we find a big discrepancy there, we get to play the favorite game of tech writers everywhere: Let’s You and Him Fight!

Looking out for existing customers

Another benefit of reviewing release note information with customer-facing teams is learning about how those changes might affect existing installations. In the rush to get a feature coded and released, the people directly involved in that process can sometimes miss how the change could break legacy systems or existing customer workflows. This also depends on how backwards compatible your systems are, but with SaaS/PaaS products, it’s usually pretty important to avoid breaking having the new stuff break the old stuff. And if that has to happen, it usually happens in major releases. It also requires a lot of communication with existing customers, to make sure that they remain your customers.


A change that breaks existing systems requires a bit more than a warning in release notes. That sort of information can fill an entire migration guide. But other than that, the structure of release notes should be fairly consistent between major and minor releases.

I usually include three main sections: New features, bug fixes, and, optionally, known issues. That’s been pretty uniform, in my experience; any more than that and the release notes get too cluttered, which means less likely to be read.

The first two, features and fixes, are the info you get from PM, engineering, and by looking at the engineering team’s task tracking system (did I mention that? First thing you do at a new company: Get an account for the whatever system they’re using).

Promoting the good stuff

The “good stuff” being the new features. Everyone likes new features, and that’s what your marketing team is going to focus on in their communications about the release. Fixes are great, but that just means your product is working the way it was supposed to when the customer bought it. But new features are…well, new. They’re neat little presents, ready to be installed and incorporated into a customer’s workflow.

So these are the easy ones: Everyone wants to boast about new features; the most difficult part is understanding how they work, why they were added, and then explain that in a couple of sentences. I don’t like to include long descriptions in release notes, since I figure that if someone is interested, they’ll follow the links to the docs that provide more detail (so: provide links!).

Listing the fixes

I’ve seen the most confusion about fixes: which to list, and why. There’s no point in listing everything that’s been fixed in the release; that list will include bugs that were created, discovered, and fixed during the development process.

Instead, I stick reporting the fixes for bugs reported by customers, or that customers were likely to have seen (and suffered through). No company wants to air their dirty laundry, so to speak, and listing bugs that no one saw looks like your product has a lot of bugs. Not that any product is bug-free, but no one likes to call attention to that fact.

But even this is difficult: Some companies want to limit the list to the highest-priority bugs. Then customer support can reach out to customers with information about lower-priority bugs that they reported. This solution requires more work from the support team (or whoever has to compile the list of customer-reported issues that were fixed), but it keeps the list of fixes in the release notes short and  manageable.

Include known issues?

As opposed to confusion, listing known issues that remain in a release inspires active conflict. Marketing worries that competitors will mine this list to spread FUD (fear, uncertainty, doubt) as they try to capture your prospects and pry away existing customers.

I’m ambivalent about listing known issues. On the one hand, they do give your customers warning about possible problems, and they should also provide workarounds. On the other hand, a customer will rightly ask why you didn’t fix those bugs if you know about them.

Not that ignorance is an excuse, of course. Plus, acknowledging the bugs might lead your customers to infer that you plan to fix them at some point. A known issue section can take pressure off your support team, but that assumes that a user who encounters the bug has read the release notes, and remembers that known issue. But at least support can copy and paste the relevant section in their response (or just tell them to RTFM if they’re less helpful).

This is the sort of thing that leads to cross-department battles. I’ve worked with some product managers who hand me a list of known issues, and others who couldn’t understand why you’d ever want to reveal that information. Now that I think about it, the latter PMs were more attuned to product marketing.

My view is that we should warn customers of issues that an average user is likely to find when using the product. Definitely report them if they can cause serious problems (although, again: Shouldn’t those be fixed before the release?). But it’s also nice to warn customers about annoyances, and reassure them that you know about those and will fix them soon. Or soonish.

And more…

I’m going to split this into two posts. Next week, I’ll go into more detail about gathering the information, and when and how to let your customers know about the great things that you’ve been working on.

One thought on “Everything I know about release notes. Part 1.

Comments are closed.