Learning to love release notes by Anne Edwards

Anne Edwards’s talk about her experience with release notes had everyone laughing. You can probably tell what kind of crowd there was at Write the Docs Prague 2018.

Anne is a technical writer at Improbable and her job involves writing all manner of technical documentation – including release notes, which was the subject of her talk. Anne has also uniquely fused poetry and documentation, which is a refreshing approach to say the least.

Her background in philosophy and linguistics has helped inform her conceptual approach to writing release notes, and made her presentation rich with takeaways you can apply to your own work.

Definition of release notes

Anne’s first stop in researching release notes was, of course, Google. She struggled to find a good definition of release notes once she was there.

Wikipedia offers a very general definition of release notes that doesn’t cite any sources, which leads Anne to believe that no one really knows what a release note is. At the very least they are an informal practice with no standard structure.

Image caption: Wikipedia’s definition of release notes

Wikipedia says:

“Release notes are documents that are distributed with software products, sometimes when the product is still in the development or test state (e.g., a beta release).

“For products that have already been in use by clients, the release note is delivered to the customer when an update is released.”

What particularly struck Anne about this definition from Wikipedia was a lack of consistent format for release notes. Here’s Anne’s own definition of a release note:

Image caption: Anne’s definition of a release notes is:

• A list of bullet points published alongside a software release
• Bug fixes, new features, known issues
• Not very glamorous, but necessary
• Often an afterthought, frantically pulled together at the least minute

Release note haikus

Release notes have a habit of being tricky to write and yet wholly necessary to delivering a software product – especially one that is being continuously iterated upon.

Anne’s experience with release notes at her work prompted her to turn some of them into haikus. This may have been partly out of frustration, but also so that she could get to the heart of the meaning of each release note.

In case you are unfamiliar with the format of a haiku, it is a short three-line poem (originating in Japan) with the number of syllables per line being 5, 7, 5.

Release note haiku 1:

Image caption: Perfectly normal action no longer causes everything to break

Release note haiku 2:

Image caption: The behaviour is no longer the opposite of what you’d expect

Release note haiku 3: 

Image caption: Finally added a feature you requested seven years ago

The peals of laughter from the audience at Write the Docs suggests many members of the audience empathized strongly with Anne’s point.

Rewriting release notes in a new company

Following the haiku exercise, Anne then moved to her current role at Improbable – a company that delivers software for game developers creating games with large online worlds.

At the time Anne joined, the company developers were writing the release notes. She initially thought this was good thing. Developers were the Subject Matter Experts, after all.

However, Anne soon found that developers writing release notes resulted in documentation that was not particularly user-friendly.

There are a number of reasons why it’s tricky to write release notes, so we’ll go into three of them now.

Too close to the product

Although the developers knew exactly what was going on with the software, they were too close to the product. At the same time, none of them were particularly knowledgeable about the users themselves.

This meant developers were writing notes from the perspective of the people engineering the software, and this didn’t make a whole lot of sense to the ones actually using it. Or anyone else, for that matter.

Image caption: A release note Anne didn’t even understand read “Previous unresponded command responder will not be lost when a new command is received before it is sent.” 

It’s difficult to ask someone to redo their work, so you must do it with some tact.

“My approach to tackling release notes I didn’t understand was to ask the developer to make the release note longer, but hopefully making it clearer in the process,” says Anne. She then rewrote the note again in a simplified version.

She developed a specific framework to make this process easier using the terms “previously” and “now”. “Previously” refers to what the software did before, and “now” to what the software does now.

Writing in an overly formal tone

Another problem with release notes is they’re produced by people who don’t necessarily write as their primary role. They often try to make their writing sound more “official” and write in a very abstract manner.

Image caption: The overly informal release note read “It is now possible to directly use X, Y and Z as return types for commands. It is not necessary anymore to wrap them in a user-defined type.” 

These are perfectly natural tendencies but Anne had to make the release notes more direct and talk to the user. Most technical writers are usually trying to get away such a style in their documentation.

This meant Anne removed some of the formal language by replacing passive voice replaced with active voice, for example. She also uses second person pronoun “you”.

Writing like a stand-up

Other times, developers wrote the release notes from the perspective of being in a team stand-up.

During a stand-up, it’s custom to talk directly about the code you’ve written, but this information isn’t particularly useful for the end user. This results in opaque, impenetrable release notes.

Image caption: Stand-up focused release note reads “Added the A and B fields to the C struct returned by D”. 

Anne helped rewrite the stand-up style release note to focus on what the software now does for the end user.

These three problems succinctly illustrate some of the issues associated with writing release notes. Anne’s overall advice relating to release notes is: “Don’t make the user work to untangle the release note.”

The “quirky” release note

Anne realized she was using the same techniques frequently. She wanted to find out if there were any templates online that people normally followed to write release notes.

Again, she failed to find any guidance on Google. All she found were guides where people encouraged her to write friendly, quirky release notes. This goes to the other end of the spectrum of the overly “formal” release note.

Anne had a lot to say about the idea of the “quirky” release note, which is a current trend in copywriting. The idea is to write in a very informal, conversational register. Here’s an example:

Image caption: Quirky release note example

In Anne’s opinion, release notes shouldn’t be “quirky” – or at least not at her company. The problem with this sort of release note is:

• They’re really wordy
• Makes more work for the reader
• Use humor, idioms and slang
• Likely to divide opinion
• Obscures meaning
• Doesn’t reflect everyone’s brand voice
• Confusing to non-native English speakers

Don’t write in a quirky way unless you really, really have to.

Adapt to your environment

Anne’s overall advice when it comes to release notes and style guides is to adapt whatever you write to the environment you’re working in. Don’t have quirky release notes at a very serious company, for example.

A lack of information led Anne to develop her own release note style guide for her company and tackle the original problem – the lack of a consistent format.

She wrote the style guide to help the other technical writers and also developers, sharing some of her insights as a takeaway for anyone to use.

Here are some of Anne’s basic principles for your release note style guide:

Image caption: Style guide basic principles are: 

• Be accurate, clear, and concise (in that order)
• Be user-focused
• Give enough context

Here are some things you shouldn’t do:

Image caption: You don’t need to: 

• Start bug fixes with “Fixed…”
• Be formal and impersonal
• Go into great detail

And some tips and tricks:

Image caption: Style guide writing tips and tricks: 

• Expand and simplify – as though you’re solving an equation
• Image you’re talking to someone – what do they care about? What do they need to know?
• Use a template – less brain work for you and your readers

When rewriting your release notes, you might find everything gets worse before you get better – like tidying your house.

“You have to make more of a mess before you get everything into its right place,” says Anne.

Final remarks

Release notes are a necessary part of software development but it’s an area where you can also have fun and be creative.

Don’t get too bogged down into making an overly rigid style guide that you have to force everyone to stick to. “The guidelines are there to help rather than restrict your release notes,” says Anne.

When writing your release notes, remember:

• Keep it clear and concise
• Focus on the user
• Be direct

Happy writing! Here’s a link to Anne’s talk recording on YouTube and her speaker deck from the talk. You can also find Anne on LinkedIn.

Our knowledge base software KnowledgeOwl enables technical writers to publish outstanding documentation. Sign up for a free trial. 

Photo credits: Attribution-NonCommercial-ShareAlike 2.0 Generic (CC BY-NC-SA 2.0)