<!-- Content Here -->

Where content meets technology

Oct 10, 2017

Release notes: the most important documentation you will ever write

One of my favorite high school teachers used to say "if you want to learn about the world, read the newspaper." This is great advice because, by updating you on what is happening now, newspaper articles expose you to places, people, and histories that you can dig into more with additional research.

I feel the same way about release notes. Let's face it, people don't read product manuals cover to cover any more than they do encyclopedias. You read a reference resource when you want to learn more about something that you are already aware of. In the product world, you read the manual when you are struggling to figure out how to use a feature. But what if you don't know a feature exists? That is where release notes come in.

If you practice lean product development, your product should be constantly improving so there should be plenty of material to talk about in release notes. You should also have an engaged customer base that likes the product, wants to learn new ways to use it, and is excited to know what is coming next. Release notes are the ideal channel to educate these customers about product features and progress. So make your release notes good!

While they are not release notes in a classic sense (because they are not tied to individual releases) a good model to follow is the "What's new with Alexa" emails that Amazon Echo owners get. These emails are easy to read and have just enough information to tease the reader into trying something and learning more. They also mention older features that new users may not have heard about yet. In fact, I am convinced that some weeks those emails only contain older features. But they are still useful reminders!

The redesigned App Store for iOS 11 also has some of these qualities.

I pay a lot of attention to release notes for all of the products I manage. Here are some habits that I think make them successful.

  • Write the first draft of the release notes at the start of a release cycle. That is, when the release is scoped and getting prepared for QA.
  • Invite internal stakeholders (especially sales, support, and QA) to review and comment on early release notes drafts. You might learn about functional issues that were not considered during the initial design. You may also learn about how to better describe/position the feature.
  • Make the release notes fun and easy to read. I find that humor are helpful in keeping the reader's attention.
  • Make release notes required reading for staff. After sending out the release notes, I email managers a quiz question to ask their team. 
  • Keep the notes short. Focus on what the change is and the problem it solves. Talking about the "why" is critical because it helps the reader understand what the feature is used for. For more details, link to longer form knowledge base articles or product documentation.
  • Include a "new to you" section that describes a pre-existing feature that is under-utilized or not widely known about. 
  • Copy the release notes into the Git merge commit message. This makes deployed versions stand out and searchable.