writing release notes (bug descriptions)

Five or so years ago, I wrote these guidelines on how to write release notes for the software developers I work with. I’m happy to say that I still get asked for copies.

Where I work, we generate lists of release notes directly from our bug-tracking software. For each bug that we plan to reveal to the customer, the software developers write draft release notes and draft workarounds right in the bug tracker, and then technical writers (like me) go in and edit their text. Then, right before a software release, we press a button and get our list of issues for the customer.**

The release notes process likely varies a lot from company to company, but I am posting these tips here anyway in the hope they may be useful to someone else. (I couldn’t find much advice online when I first started working on bug descriptions.) I’ve included sample problem descriptions as well as workarounds.

How to describe a software bug

What do customers need to know? Give them just enough information so that they can recognize and respond to an issue. Things to consider:

  • Symptom—How will the customer recognize the issue?
  • Trigger—What customer action or particular configuration or some combination thereof might cause the issue?
  • Operational impact—What is the effect in the customer environment? (I work in the IP routing domain, so some examples here are things like dropped sessions, accounting errors, access problems, upgrade issues, and so forth.) If there is no impact, or if the issue is display-only, say so.


How to write a workaround

Things to include:

  • How can the customer avoid the problem?
  • How can the customer recover from the problem if it does occur?


Information to exclude

  • Hidden commands (ones the customer will not see)
  • Customer names
  • Real user names
  • Code snippets
  • Feature IDs
  • Code snippets
  • Low-level details, such as the interaction between internal processes

Always describe the bug as if it were open (even after it’s fixed)

Even if you publish lists of fixed issues, as we do, I recommend you do not revise the bug description to put it into the past tense after you fix the bug. It’s too much overhead. We think it’s enough to include the issue in a list called “Resolved Issues.” Also, this approach will allow you to handle a bug that may be open in one software branch and fixed in another—you can get by with a single description that works for both cases.

Also, if your bug-tracking software includes separate fields for the release note text and the workaround text, you can omit the workaround when you generate your list of fixed bugs.

**OK, it’s a bit more complicated than that!


Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Google+ photo

You are commenting using your Google+ account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )


Connecting to %s