5

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.

  • Can you revise the question to emphasize how it relates to project management? As stated, this is more a software engineering question. – Mark C. Wallace Nov 16 '15 at 11:26
6

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.

3

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.

  • We really never did release notes until now. The business had no requirement for one, other than a complaint about not knowing what just went live. I'm simply including a list of features that they've requested which were implemented in the current release, along with the descriptions from the requirements documents. They really just want visibility into what changed. – Mark Richman Mar 18 '12 at 21:17
  • 1
    If that isn't enough to work out what they want, maybe deliver something and ask for feedback. It's what I do for projects. – Lunivore Mar 18 '12 at 22:57
0

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.

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Not the answer you're looking for? Browse other questions tagged or ask your own question.