Release Notes Writing Checklist: 7 Don’ts and 13 Do’s

If your technical writing job involves writing release notes, create checklists for writing, reviewing, and production.

Use the following checklist to review release notes.

Avoid the following mistakes when writing release notes.

1. When – use if instead use when. The difference between when and if is that when implies something has occurred, for example, when I click Window Y, an error appears. That’s fine up to a point. However, if states a condition. If I click Window X, an error appears. In other words, if highlights to the reader the conditions that contribute to the error. It’s a subtle difference but worth noting.
2. Gerunds — avoid using -ing constructions, such as, it was printing. Instead write it was printed. Remember, a but refers to something which has happened in the past. It’s over. Past tense. It’s not happening right now. For that reason, use past tense phrasing when writing the bug section of release notes.
3. Incorrect in bug description heading — don’t use incorrect, bug, or issue in the release note heading as it’s already implied.
4. Dialog box — not dialog or dialogue.
5. Value not field — write the ‘The value in the Net Amount column on the window…’
6. Displayed — write the list was not displayed, not missing. You can also write, ‘’The window was blank’ if nothing was displayed.
7. Bullet – avoid single line bullet lists. If only one bullet, add it to the preceding sentence.

Use the following checklist to review release notes.

1. Spellcheck — select the entire document, apply the correct language setting, then spellcheck. If you don’t do this, the spell checker will skip text in different languages that may have been pasted in.
2. Installation directory — are the paths to the installation directory correct?
3. Section Title – check for Case. Make sure the correct works are in lowercase, such as for, in, of etc.
4. Code style —is the code style applied to parameters, xml elements etc.
5. Italics style — is the italics style applied to book names, chapters etc.
6. Bullet list styles – are the correct start, continue and end bullet tags used?
7. Length – use short sentences. If a sentence is more than twenty words, create a new one.
8. Phrasing — Start with ‘This issue occurred if…’
9. File Affected — check these are correct and complete.
10. Book Affected — check that any affected technical guides are mentioned.
11. Index Markers – if the heading or release number is changed, update the index markers.
12. Command v Button – remember the difference between a button and a command. Double-check and use the correct font
13. Tables – make sure every table has a caption.

Summary

Creating checklists requires a little work in advance, but ensures that your release notes are accurate, consistent, and reflect well on you as a technical writer.