Release notes – less or more structured approaches

Continuing my post from last week, I’ll briefly explain how we maintained a change log in my company for about an year (this was back in 2009) and what were the the things we liked and disliked about it.

We used a shared OneNote notebook that had a page per each internal build. After a developer had checked-in a bugfix or some new functionality, he had to describe the change in a free text format, Pasting screenshots was encouraged too, when applicable. The OneNote looked like that:

We chose OneNote because of its several conveniences:

• Easy to setup and use.
• Allows concurrent editing.
• Easily searchable.
• Allows WYSIWYG rich text formatting (including pasting screenshots)

Actually we didn’t use many OneNote features. It was just a visually appealing and easy-to-setup wiki. I think it was pretty useful for devs and QAs in terms of shedding more light in the product development. People could quickly got a good idea how features were evolving and be kept up-to-date with the changes in a non-obtrusive way.

But there were several things that were not that great about this process:

1. Some developers complained that it was getting too difficult to commit changes: first they had to write checkin comments, then they had to write a resolution in the issue tracking system, and finally they had to update the change log. Though the comment text could slightly differ, sometimes it seemed like a duplication.
2. It was not that easy assemble all the changes for the official release notes from the changelog. One of the reasons was that changes were organzied by date, while it made more sense to have them finally grouped by component and sorted by importance. Also the writing style of developers differs, so it was necessary to rephrase many of the changes.
3. Since the log has loose structure, it was not possible to query the changes, e.g. “find me the fixes by developer X made in the past 2 weeks”.

So I was thinking why not capture all release notes information in the issue tracking system itself. The advantages of such approach are obvious, but the system has to meet several requirements for this to work well:

1. Support custom fields (for a text field “DescriptionForReleaseNotes” and probably another one “ImportanceForReleaseNotes”)
2. Support specifying in which release was the change made.
3. Support specifying the component that changed.
4. Support generating a custom report that for any selected release(s) outputs the non-empty changes, grouped by component and sorted by importance.

I guess that most popuplar issue tracking systems would support the first three features. I have my doubts only for the report, but some systems might offer powerful enough reporting out of the box. And even if they don’t, exporting the result to Excel and doing some data manipulation there, is an option, too.

Another challenge is that this approach assumes that each item in the release notes should describe only one issue in the system, which is not always the case. You might want to group several small changes in one area in a single item. Well, you can just put a value in DescriptionForReleaseNotes for only one of them, but it will be difficult to manage this, unless there is a support for linking the other related issues to the one that contains the description. So linking issues is probably another requirement for this approach to work well.

So is it worth commiting to such a highly structured approach of storing release notes? I am not sure. If your issue tracking system can handle such process well, it might be relatively painless to adopt it. But if you have to use another tool just for managing release notes, it might be an overkill. What do you think?

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:

.NET control suites: Telerik , Infragistics, DevExpress, ComponentOne.

VS.NET addins: ReSharper, TestDriven.Net, Typemock, Entrian Source Search

SCM systems: Mercurial, PlasticSCM, Subversion, Vault

If you looked at the release notes, you’ve probably noticed that they differ both in terms of content and presentation:

Content

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 :) )

Presentation

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).

Continued…

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.