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.