[Checklist] Document Reviews

Use this checklist to review business, medical, or technical documentation.

It is recommended to review the document for start to finish for each item on this list, instead of reviewing all items as you go through the document. In other words, check that all images are correct throughout the document. Fix any errors. Then go to the next item, for example, grammar and check this.

This approach tends to be more effective as you can zero in on each specific item instead of trying to catch them all as you scan through the text.

Variables

Use the correct style. Make sure the variables are updated and correct before publishing.

Terminology

Be consistent. For example, avoid using terms such as folder, sub-folder, and directory, if they mean the same thing.

Images

Make sure that the style guidelines are applied to all screenshots. For example, if developers have sent you screenshots, they may use a different colored box or arrows. You need to fix these in SnagIt or ask them to send you screenshot without captions, boxes, and text.

If possible, keep them the same width and height.

Crop the image so the most useful part of the graphic is displayed. You don’t have to show the entire window, instead highlight the part that’s of most use to the reader.

Avoid special effects, such as jagged edges, which can look inappropriate or dated.

Remove noise.

Use the same MS Windows theme for all screenshots.

Procedures

• Check the number sequence.
• Watch for images that may have accidently been numbered.
• Watch for captions or notes that may have accidently been numbered.
• Check that the phrasing is correct.
• Be consistent. For example, avoid different phrases creeping into the document, for example, Click the Print button, Click Print, and Click [print icon].
• Check if sentences finish with a full stop (period) or not, depending on your style guidelines.

Em Dashes

These are double the width of en dashes. The phrasing we use is as follows:

Item Em dash Sentence starts with uppercase.

For example,

Printer–Check that the printer is installed.

Note that there is no space on either side of the em dash.

Spell-checking

• Watch for words which may have been entered by accident, for example, form instead of from. These will not be identified as errors by the spell checker.
• Don’t trust MS Word spell checker. It does a good job but is a crude instrument.
• Select the entire document, and apply the correct language setting.

Document Properties

• If you didn’t use a new, blank template when you started, the document properties of the original document will be displayed in Windows Explorer and in the PDF.
• To fix this, click File, Info tab, Properties pane.
• Click Properties and then update the Title, Tags, Comments, and Author. If you mouse over the document in Windows Explorer, you can see the document properties.

Code Samples

If you use code samples, make sure they use the same style, eg code, and are clearly not part of the main text. It’s recommended to use a specific font, such as Courier New. Add a caption for each code sample. Check that it’s correct, especially if others have reviewed the document.

Product Name – look out for product names which may have changed either during the document development, for example, as part of rebranding. Check that logos reflect this, if affected.

Text

• Sequence – check that chapters are in the correct sequence. While they may have started in the correct sequence, after multiple reviews and the inevitable copy and pasting, the sequence and order may have changed.
• Use the same phrasing in tables, lists, figures
• Images – flush with text, include captions, number caption. Check that caption numbers are updated.

Temporary Text

Remove any placeholder text, such as notes to developers, placeholder text for images or text to be inserted, comments, questions, or other text that should not be part of the final document.

Track changes

• Ensure that all comments has been merged and addressed in final document.
• Check that track change bars are not displayed in the PDF.

Headings

• Use the same phrasing, for example, procedures start with a gerund.
• Use the same structure, for example, mixed case.
• Use the correct style. While this may be obvious for H1 and H2, check that H3 and H4 are styled correctly.

Writing

• Possessives – avoid where possible as we may want to translate the document later. However, avoid lengthy sentences simply to adhere to passive voice, for example, multiple ‘of the’ type phrasing.
• Spell Checking – select the entire document – CTRL+A – and change the language setting to the correct language. Foreign language can creep into the document during cut and pastes. If necessary, copy the entire document to Notepad, then paste back into a clean MS Word document. Spell check this.

Header

Check that the correct logo and document name are displayed. Watch out for section breaks which may cause the header to disappear. Also, if you change the document name, make sure to update it in the header. Finally, if you use field codes, press F12 or manually update the fields.

Footer

Check that the correct format is applied to the page numbers, that the pages are in the correct order – section breaks can make them disappear – and also that the pages are displayed on the correct side of the page.

Table of Contents

• Update the Table of Contents and use the navigation pane to check that all sections are displayed correctly.
• Check that all Heading 1 sections appear.
• Check that all sections are styled correctly, eg heading 2 don’t appear as a Heading 1 or the other way around.
• Check that text or images have not crept into the Table of Contents, for example, text in first paragraph following a chapter heading picks up the same style by accident.
• Update the Table of Contents after you review the document and give it a final check. Look out for duplicate entries and blank entries which can occur if a new line is entered after say a chapter header, but text is not applied. Or a section or page break is created which accidently uses a heading style.
• When finished, press F9 and update all fields in the document.