Journals by RSS
Journals by EmailOne of the principles of Agile development is that you work in segments of time (iterations and cycles) on chunks of functionality that can be released at the end of the segments. This encourages frequent releases, which are good for users because they get new functionality and fixed bugs more often. Obviously, the amounts of functionality and fixed bugs are smaller, but more frequent releases give a sense of progress.
I’ve been working on some release notes today, a deliverable that we just decided to add to a particular project (it’s not a standard deliverable in our department). Previously, I had a “What’s New” topic in the help system, but I was usually caught up enough with getting the updated documentation finished in time for the code freezes that this topic fell to the bottom of my list of priorities. But I like the idea of having this kind of document.
This edition of release notes includes three parts: enhancements, bugs fixed, and known issues and workarounds. In the next release, I’m going to include a section on user-reported bugs and their progress. We’re not ready for that this time because we need to have a better way for obtaining a list of those items. Usually, you don’t see a list of bugs until they’re fixed. However, I think it shows the user that you’re listening when you list which bugs they reported and you’re working on but haven’t yet fixed. It may hurt a little because it says, “We haven’t yet gotten this taken care of for you.” But at least you’re saying that it’s slated for fixing.
Tom Johnson and commenters’ discussion of release notes is interesting. The conversation reinforces the fact that different managers and teams prefer different things in the release notes. For this first run, our general guideline for which bug fixes to list is to exclude the ones that are back-end problems, things that the user would probably never encounter.
(The fact that release notes are new for this project and not a standard in our department reminds one of the fact that we still have some way to go to make documentation deliverables an official part of the process. But we’re getting there.)
Something that I think is important, however, is the known issues and workarounds section. The users will encounter certain problems, and to head off frustration, we want to let them know that they can get around the problem and get the job done. It also lets the users know we’re aware of the problems and aren’t sweeping them under the rug.
On a completely unrelated note, I walked past a parking lot entrance booth today, and the worker inside was playing the harmonica. Nice. When you have that kind of job, you’ve got to find something to pass the time when nothing’s happening.
Related entries (auto-generated):
A Process for Developing Regular Release Notes
Reveal Bugs in Release Notes, Not User Guides
Release Scrums: An Important Resource for the Agile Technical Writer
1 Comment to 'Elements in Today’s Release Notes'
February 6, 2009
I haven’t read Tom et. al discussion about release notes, but your post brought a smile to my face. I worked for a fantastic software company in the mid-90s. I asked once about release notes — if and how we planned to use them with each production release. The lead programmer said, “Oh, we already do that. It’s the ReadMe file that gets distributed with the executable.” I asked him who typically installs the software at the client sites. He said, “We do. The install is to complicated for clients, so we go to each site and do it.” I didn’t have to make the obvious statement. The look on his face and the rest of the development staff said it all. Thanks for allowing me that great memory from a really fun time in my career.
[Reply]
Set Me Straight. Leave a Comment.