How to write release notes

I confess, I’m a release notes reader, and I’ve read some overwrought release notes lately. When you use them like an installation guide, a features list, or a list of software conflicts, you’ve got it wrong.

The purpose of release notes is simple:
Release notes explain what changed with this version of your software. Period.

I hope this article will help you write release notes with clarity and brevity.

Title format for release notes

The title for your document should include specific information:

  • Name of product
  • Version number

For example, if your product is RubberDucky and this release is version 3.3.5, the title for your release notes document should be RubberDucky 3.3.5 Release Notes.

Make the title big and bold at the top of the page. Refer to it in links exactly as the title reads.

Consider following the title with these bits of information.

  • One sentence overview of the product
  • Date of the release
  • System requirements
    • Note changes, like “Discontinued support for Windows XP.”
  • Link to installation instructions
  • Link to a user manual
  • Link to a release notes archive

Other sections in release notes

Break the release notes document up into sections, each with its own heading. Here are some sections to consider.

  • Additions
  • Removals
  • Changes
  • Fixes

Keep the actual descriptions brief. Release notes are often little more than a bullet list of updates, and that’s fine. If there are a series of small technical changes, try to describe them as a theme. For instance, “Improvements to the communication between the software and our servers.”

However, if there is an update that is important for users to understand, do not sacrifice clarity for brevity. Write enough of a description to explain the feature, but no more than necessary.

How do you know if an explanation is too short or hard to understand? Ask someone who is familiar with the software but doesn’t really know about the release to read the explanation and explain it to you in his or her own words.

What about personality?

Release notes should be easily scannable, and inserting witticisms should be avoided. However, if the company is proud of some feature, it doesn’t hurt to brag about it, so long as it is brief.

Here’s a nice example from TextWrangler 3.0 Release Notes.

Brag about it. Snippet from TextWrangler Release Notes.

BareBones Software inserting a little attitude into their release notes.

What about posting existing, known defects?

This question quickly becomes a philosophical one. In my opinion, a company should be transparent about known defects with their software and earnestly try to fix those problems. You can see this type of behavior with some open source projects in that they have a public defect tracking system. The bugs are out there for the world to see. With enough of a user-base, defects with your software will probably become known eventually anyway.

However, I do understand that in some cases advertising known-defects is a security and stability liability and just shouldn’t be done. My preference is that that sort of decision is made on a defect-by-defect basis, and not as a corporate blanket statement.

Regardless, known defects or incompatibilities do not belong in your release notes document. You could, however, link to a list of them in your release notes.

Organizing archival release notes

What do you do with all those release notes from prior versions of your software? Archive them on your website so you and your customers can get to them.

One page, all release notes

If your release notes are brief, you might want to include each version on a single page. The most recent release notes should be at the top of the page. Fetch Softworks currently takes this single page for all notes approach.

One page of release notes per version

For the sake of clarity, I would prefer to have release notes for a specific version on that single page, with a release notes archive page that links to every version. BareBones Software takes this index of release notes approach.

Some companies keep a current release notes page up-to-date so they don’t have to continue updating links. Again, BareBones follows this approach: http://barebones.com/support/bbedit/current_notes.html

Do you have good (or bad) examples of release notes?

Not having seen any “best practice” document for release notes, I wrote this article. Do you agree? Disagree?

If you have examples of great, or really awful, release notes, please comment with the web addresses so we can all see them. Thanks.

16 thoughts on “How to write release notes

  1. elianna james

    our primary use of “release notes” is from Project Management to Business, Upper Management and Customer Support. They are MUCH more verbose than you suggest in this article.

    The primary audience that needs those notes is Customer Support and typically, they still need some more detailed info on what changes/ updates/ feature removals have occurred.

    Good topic and I’d like to see more in the future.
    thanks for posting.

  2. Davin Granroth Post author

    Thanks Elianna. Good point. I think of the release notes you describe as a certain breed of release notes for internal use. There may be details that you would share inside a company that you would not share to external audiences, perhaps because the information is sensitive or it might only make sense to people in the company already.

  3. Latha

    Hi, Davin,

    Release notes are required when we send the Requirement document to client?
    What is different between Release note and Release notes?

  4. Davin Granroth Post author

    @Latha Elianna may have commented about about a similar type of release notes. This article is really about release notes made to describe a software release to the users of the software. Since you mention a requirements document, I wonder if you are talking about a document describing release planning notes as used in Agile (like Scrum) development, which would provide a list of user stories (features) that make up a future product release? That’s a very different topic.

  5. Zeba

    Typically who should write the release notes for the software? A member from the development team or the tester who tests the release..???

  6. Priti Gaikwad

    A colleague insisted on including details about the next release of the product under the heading, ‘What to look forward to’ in the release note. I have not seen many instances of Release Notes with that format. I think that mentioning the next release details may increase customer expectations and if the release plans and features list change, it would disappoint customers. Please let me know your thoughts on this.

  7. Dawn Baird

    I’d be keen to know other technical authors’ thoughts on the following:

    Do you include the following headings: Dropped Features or Coming up Next?

    Do you include a Caveats section? I’ve seen a blog recommending this, but isn’t it covered in the Known Issues type sections? If you do include it, what do you put in it?

    Do you add a Changes to the Release Notes section? If so, what do you put in it?

    I guess there is so much conflicting advice online, I’m wondering if there can be any consensus?

  8. Davin Granroth Post author

    @Zeba Good question, but I don’t know. What about someone from marketing to write the release notes? I think before it is published the release notes should be reviewed by someone (e.g., dev, QA, a project manager/product owner) for accuracy.

    @ Priti I agree with your stance on this one. Release notes are supposed to explain what is different with this specific release, not past or future releases. Foreshadowing features to be released soon can probably be done in some other way.

    @Dawn Thanks for these questions! I agree, it seems like this type of document is still unclear. I hope others will chime in on your questions. Also, if you have a link to some other release notes that we can consider, would you post that? On “dropped features” I’d say that it is important to include, since that would be a change to this version of the software. Upcoming features perhaps isn’t appropriate though, since it doesn’t have to do with this release. Where might that go? A corporate blog post? The product page in a highlight teasing an upcoming release?

    And, I’ve never even thought of a “Change to the Release Notes” section.

  9. Sean Kowallis

    When creating release notes, would a hot fix need to be listed? I always thought hot fixes are made to address a specific customer situation.

    Also, does software jargon need to be eliminated or explained in detail? The type of jargon I am referring to are terms users might encounter when using the software.

  10. Diane Emory

    I write the release notes for a software company and they are quite long (100 pages before I took over the writing, and I’ve gotten them down to 30 pages). The product manager keeps asking me to include screenshots and procedures and I keep telling them that these kinds of things don’t belong in release notes, and that users should refer to the online help for information about using a new feature. Have you ever seen procedural information and screenshots in release notes?

  11. Davin Granroth Post author

    @Diane Wow! 100 pages of release notes for a single release? Nice job at trimming them to 30. To your question, I have seen procedural information and screenshots in user guides/manuals and online support documentation, but not in release notes. It sounds like you and your product manager have different definitions of “release notes.”

  12. sayli

    Great article and nice tips. this helped me create an outline for a release notes template. However, is there no standard for documenting release notes in software quality documentation from ISO or CMMI?

Leave a Reply

Your email address will not be published. Required fields are marked *

You may use these HTML tags and attributes: <a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <strike> <strong>