A Process for Developing Regular Release Notes

Monday, February 22nd, 2010 | Team Dynamics, Technical Communication

In my project portfolio, our release manager—the one who instituted release scrums—wants to standardize on release notes across applications. Many of the projects are in a maintenance period, so releases are planned for each project every month or two on something of a rotating basis. These releases will include small enhancements and bug fixes.

One of the challenges of standardizing on release notes is coming up with a release notes process that can efficiently turn out these documents within about a week.

My release notes include the following sections, as applicable:

Tips for preventing and solving problems: Instruction on items that have caused some users trouble
Enhancements: What’s new in the application
Fixed bugs: Fixes on bugs that users have reported
Known issues and workarounds: Open bugs or other problems that haven’t been fixed, along with ways to get around them

I attend project scrums and release scrums regularly to stay up on what’s new and what problems have emerged. Another tool I use is Atlassian JIRA, the Web app that the teams use to track user stories, development tasks, and bugs.

Here’s my ideal process for developing release notes:

The developers and testers keep tasks and bugs up to date in JIRA, including resolved and closed statuses. This includes having a category for each release and connecting each item to a release.
About a week before the release, I look at JIRA’s list of items for the upcoming release. In a perfect world, all development is done at least a week before the release, and the testers are regression-testing and developers are hardening the code. The only bug fixing they do is on bugs they introduced during the last development iteration or cycle.
I add items to the enhancement and fixed bugs sections of the release notes based on what is closed (or resolved) and will affect the user experience. Some fixes, like database refactors, aren’t going to affect the users, so I don’t mention them. As needed, I look at enhancement or bug descriptions and ask developers and testers for more information to determine if I should include those items and how to describe them.
Two or three days before the release, the product managers review the notes and give feedback. If necessary or possible, it can help to have a QA lead review them as well.
Within the next day, I incorporate any changes and send them back for a second review. We repeat this as many times as needed.
Notes are distributed through the product managers. These are internal applications, so we aren’t creating a place to post the notes publicly.

It will take some coordination with the teams to make sure that some things are happening, but I have buy-in from the program manager and the release manager. Besides, the team practices I mentioned in steps 1 and 2 are probably just good project management anyway. Different projects are doing them in different amounts, and it could only help to make our processes more standard across the portfolio.

Share This