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?