Release notes – whats and hows
So you are asked to prepare a detailed list of changes in the last N months that would be the basis for creating the release notes for the brand new shiny version of your product. Unfortunately you have not been maintaining a change log throughout the product development. Naturally you can’t come up with a detailed list from the top of the head (even for the stuff you developed yourself). In order to do a decent job, several people have to invest hours (or days) to dig out stuff from various sources: the SCM system, the help desk, design documents, e-mails. Under time pressure they have to formulate the changes in a way that they make sense for the target audience. And if the deadline is tight, you might sacrifice the quality of the release notes. That’s stressful and inefficient. But before digging deeper on how to take preventive measures, let’s first take a look at what’s the purpose of release notes/change log and how to prepare them.
What is the target audience of a change log/release notes?
I initially planned to use the terms “change log”, “release notes” and “revision history” as synonims. But I have a subtle feeling that a change log is for internal audiences, while release notes/revision history are targetted to the end users. A change log also seems to have a connotation of an on-going effort, while release notes are often created just before the release as a one-time effort.
It’s clear that not only the end users (current and prospecitve clients) are interested in what’s fixed/ehnahnced/added. A lot of people involved in the product development need such information and they surely need it on a much more regular basis. The list of the internal stakeholders includes QAs, technical writers, developers, customer support, consultants, trainers, management. Probably everyone is interested in slightly different subset (or aspect) of the changes, but to keep things simple let’s examine for now only the differences b/n internal and external change logs.
Targeting external vs internal audience
The purpose of an external release notes (i.e. publicly visible & easily discoverable) is not only to inform, but most importantly (from the business perspective) is to:
- Advertise what goodness the new release brings – how does it empower the user (or at least alleviate some of his pain)
- Increase the confidence in the product and the company behind it - by demonstrating that serious efforts are put in its development and that there is a significant progress on many fronts.
The purpose of the internal change log is to make sure that everyone knows what is going on in the development and to take this in consideration while doing their job. It’s necessary to have additional information about the circumstances of the change (e.g. who was the developer behind the change, so he can be contacted later). The purpose here is just to inform (not to persuade), but still the description of each change should be done concisely from the perspective of the product evolution.
How release notes should be written?
I was looking for an answer of this question myself before deciding to write this post. I found several good answers at stackoverflow and in a blog post. But let’s first take a look at some sample release notes to have some background.
I spent a few hours looking at the release notes of a dozen of products (some of which I’ve used, some I’ve just been interested in). Here are a few links of various product types:
If you looked at the release notes, you’ve probably noticed that they differ both in terms of content and presentation:
Highlights : more often than not, release notes start with an overview of the most important changes
Leaving out the bugs: some release notes don’t include list of fixes, but only improvements (or at least the list of fixes can be found in other not as easily accessible location). Since there is no bug-free software that I know of, I guess the this information filtering is geared mostly towards attracting new customers.
Level of detail: some vendors prefer to describe changes in the most laconic way possible, some are more descriptive
Automatically generated: some changelogs appear to be generated directly from the issue tracking system (or even from the source control system), but most of them look hand-crafted (especially in cases when rich output formats are used, e.g. pictures :) )
Output Format: plain text vs richer format (HTML, PDF, etc.). Rich formats are more expressive & more visually appealing, but for some types of products a plain text change log might be just good enough.
Organization of the list of changes: usually the changes are grouped/sorted by component and/or by change type. The change types can be as basic as ADDED, IMPROVED, FIXED (see Telerik), though some vendors like JetBrains use more detailed types: Bug, Cosmetics, Exception, New Feature, Performance Problem, Usability Problem, Meta Issue, Task (as ReSharper).
This post got rather lengthy, so I am continuing this topis in my next post with a brief analysis of what kinds of tools you could use for manageing change logs. I’ll share some of my experience and will discuss the pros/cons of different approaches.