Release Notes Best Practices

Question

What are some tips for writing good release notes? Any best practices or examples? My audience is both my QA department and the executive team.

Answer 1

In general, release notes follow a format like the one below. You may or may not include all of these sections, depending on what is relevant to your product type and what your stakeholders deem necessary/useful for information dissemination both for them and for your customers.

• Product Name
• Version Number (Be consistent with major.minor.revision numbering in your releases)
• Release Date (name, version, and release date often repeated in the document footer)
• Type of Release (e.g. "This is a developer release for internal evaluation only." or "This is a public production release.")
• Major announcement (Not often used, but important when you need to note "This release corrects a major flaw in XYZ from the previous release. Please upgrade as soon as possible.")
• What's New (A List of major enhancements visible to the user, in user-friendly terms, e.g. "increased response time" versus "manipulated line 9 of widget #745 to change algorithm")
• Installation Instructions (Often is a list of system requirements with a link to a full installation document, but if there are compatibility issues or deviations from previous version instructions, note them.)
• Headings for: Additions, Removals, Changes, Bugfixes (The first three mean additions, removals, changes to functionality; the latter means fixes of anything. The info under each heading can come right out of your bug-tracking system and should be simple bullet points like "FIX ### Title_of_Bug". This assumes tickets are given meaningful titles. Bonus if you can link users to the bug-tracking system so they can see the entire ticket and commentary.)
• Known Issues (List of open bugs slated for next release, or prose describing known issues; this depends on your audience and what the company wants to make transparent, and how.)
• Additional Documentation (links to user guide, administrator's guide, other relevant documents)

This is a starter guide; working with your stakeholders will help massage the list into a template that works for you and for them.

Answer 2

What do the two departments / teams say that they'd like to see in the release notes? What kind of things would make them glad to see the notes in their inbox?

Generally the best release notes I've seen have almost been adverts for the releases - "This is why you want to upgrade to the new release. Here are the new business and new capabilities we're providing." For the QAs, you might also want to advertise any improvements in your processes which provide the quality control as well as the actual changes made. It depends on what they'll find interesting, and that will depend on your domain.

This is also your opportunity to showcase how well the project team has done too, so you might ask them if there's anything particular they want to include.

Answer 3

Write bugs in the past tense, e.g. this window did not appear if you used this parameter.

The bug occurred in the past but is now fixed whereas...

Write enhancements bugs in the current tense, e.g. this window now appears if you use this parameter.

As these are now available.

Finally, as regards wording be as specific as possible but don't reduce the word count it if means excluding critical information.