Writing useful release notes

Writing about technical subject matter isn’t as easy as you may think. Writing to users about changes in a technical product, with the aim of informing them about exactly what has changed and how it affects them, is downright difficult.

Take the following example:

“Synchronisation has been improved. “

This only goes part way to telling users what has changed in the product, but leaves so many questions unanswered. Like:

  • Exactly what has been improved? Is there a better response time? If so, what is it now?
  • Has a bug been fixed? If so, what is it, and what has been changed to fix it?
  • Has new functionality been added? If so, where is it located, and where is more information on it?

The example above was from a set of release notes I recently came across, and clearly wasn’t written or proof read by a Technical Writer. If it was, they should be ashamed of themselves.

Better examples would be something like:

Synchronisation performance has been improved by up to 20%, after changing the FILENAME.JAR file to make less API calls.

File names containing a ? character no longer cause synchronisation to fail. See support ticket 123456 for further details.

Support has been added to synchronize with Product X. See the “Synchronising with Product X” page in the online help file for further details.

Armed with the above information, users can:

  • Decide whether to upgrade to the latest version, if it’s not automatically deployed.
  • Identify the risk to their organisation of deploying the change.
  • Develop a test plan before deploying across their organisation.

Have something to say? Be my guest :-)

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

This site uses Akismet to reduce spam. Learn how your comment data is processed.