Release Notes: 13 Mistakes to Avoid

release-notes

It’s easy to overlook the importance of release notes.

But when customers want to know exactly what a specific parameter does, it’s the release notes that often turn too.

Why?

Remember, for very large document sets, it can hard to know which document contains the reference material you need to understand.

For this reason, configuration managers, testers, and developers often turn to the PDF release notes in search of those missing ‘undocumented’ parameters.

Now that we know that, let’s improve the way we write release notes so they can find parameters, settings, and new features faster.

Release Notes: Writing Mistakes to Avoid

Here are some of the common mistakes to avoid when writing release notes:

Will.

It’s acceptable to use the word will or shall in requirements or specifications. You’re writing about a feature that will be developed in the future.

Release notes are different. They cover what used to work (bugs) and what now works (enhancements). Use the correct tense, phrase, and formatting to reflect this.

Avoid using the word ‘will’, as in ‘the new button will let you print in 3D.’

If it’s an enhancement, explain what it does right now, not what it will do.

The new button lets you print in 3D. Or better still, the new button enables you to print in 3D.

You know why I chose enables not allows, don’t you?

Default Values

Have you identified the default values?

Developer and testers who configure the system need to know if 1 or 0 turns the setting on or off.

Usually 1 means on, and 0 means off.

But you can’t take this for granted. Highlight the default value and any recommended settings.

Tracking Numbers

Avoid putting more than one enhancement under the same heading. If possible, give each enhancement a unique tracking number. If you have to merge them, highlight that there are several enhancements in the same release note item. Don’t make the reader search.

Style Guidelines

Have you formatted the parameters, settings, or controls in line with the style guide?

The reader should see – at a glance – if something is a parameter, piece of code, or file name. Don’t mix them up!

Copy and Paste

Avoid copying and pasting text from Jira, Bamboo, or your bug tracking software. It’s easy to let raw text creep into your release notes. Be vigilant. Don’t let them in.

Dashes

Know when to use  en, em, and other dashes correctly. Use dashes as specified in the style guide.

Tip: press Ctrl + Alt + – on the keypad to create an em dash in MS Word

Punctuation

Do your list sentences end with full stops? In America, full stops are known as periods.

Typos

Avoid typos and mis-spellings in parameters. Look at the spelling very very carefully.

False Words

Watch out for repeated words, such as ‘are are’ or ‘from from’ which may have crept into the text and the spellchecker didn’t pick up.

Another example is

It previous versions

Instead of

In previous versions

See it?

Hard Coded and Field values

If you use field values in your document, say for date, author, document title, update these before publishing. You can also instruct MS Word to remind you to do this before printing. Let me know if you want to know how.

Check for copyright dates, author, title, and version number in the footer. Make sure MS Word has updated ALL fields in the document’s footer.

US v UK English

If you copy and paste from different documents, emails, and intranets, it’s easy for the language setting to change in MS Word. Your spell checker won’t highlight this. Instead, it skips the non-default text.

One tip: search for words that end in ise/ize, such as localize/localise.

Phrasing

Here’s where we need to be careful.

Phrase your release notes in line with your style guide. Give examples that developers can follow when drafting text for release notes.

The style guide gives your release notes consistency. As the text has the same common structure, the reader can scan the text and identify settings, changes, and code samples.

For example:

Instead of writing

Rather than….

Write

Instead of the…

Rather suggests a personal preference.

Instead confirms that one thing worked (or didn’t work) instead of the other.

 

Incorrect use of will

The software will import the package

write

The software imports the package

Instead of

This will be implemented as follows:

write

This is implemented as follows:

Within and in are often confused. Within refers to a period of time. For example, I have to finish the report within three day. The report is in my file.

Instead of

within a configuration file

write

in a configuration file

Incompatibilities

Finally, highlight any possible incompatibilities with the previous release. Warn the reader before they install or update the software if there is any risk data may be lost.