Posted on

How to Test Technical Documents

This checklist helps you test User Guides and other technical documents.

eye-test

The first step is to ensure the following is in place.

  1. Setup the necessary technical environment. Make sure this reflects the user’s settings or as close to as possible.
  2. Print out the procedures. Follow the instructions as per the document. Aim to identify any gaps in the steps. Likewise, see if additional notes or warnings should be added.
  3. Examine the screenshots. Does these provide real value? Do the screenshots reflect how the window or dialog box are populated? Is there data in the screenshots? If not, replace with something more meaningful.
  4. Does the introduction orient the reader?
  5. Does it highlight the necessary and mandatory prerequisites that must be performed?
  6. Are the sections in a logical order? For example, is it arranged based on the user interface layout or on commonly performed tasks?
  7. Is there an index? Are the entries used in a meaningful way?
  8. If online, have meaningful keywords been added to the search engine?
  9. Comprehensive – are all scenarios covered in the document? In other words, in addition to checking that the materials in the document are correct, you have to consider if other procedures are missing? To do this, you need to examine the application and see if, from a user’s point of view, if all tasks have been documented.

User Guide Checklist

After this, examine the document using the following checklist.

Visual Cues

Have you provided visual cues to help the reader use the manual, understand concepts, and help them digest information faster?

You can achieve this by using some of the following:

1. Headings

2. Bullets

3. Bold

4. Arrows

5. Illustrations

Support Different Learners

Have you developed content that supports the following learning methods:

1. Visual

2. Audio

3. Touch

Examples

Provide the following types of examples to help the reader understand the materials:

1. Concrete examples, for example, how to perform a specific task.

2. Abstract concepts

Document Format

Have you delivered the user guide in a file format the suits the reader? For example, do they want the document in PDF or as Online Help or both?

Other factors to consider include:

1. Size – remember to optimize the PDF before publishing and to ensure it downloads fast.

2. Online/print – prepare the document in both online and PDF, if necessary.

3. Software/hardware environment – will the reader need any special software to view the documents?

4. Binding – if delivering a hardcopy, make sure the binding is reliable, so pages don’t fall out after a little use.

5. Protection – if the document will be used outdoors, make sure it is weather-proof.

Document Structure

Have you checked that the guide includes the following?

1. Headers, footers, navigation bars

2. Table of contents

3. Cross-references/links to related procedures/documents

4. Is each topic self-contained? In other words, can you perform the task from start to finish without having to go to another page?

5. Is there adequate white space?

6. Have you avoided large blocks of text?

7. Does the document separate conceptual, procedures, and reference materials?

8. Index

9. Glossary with product terminology and industry terms

Introduction

In this section, you should introduce the User Guide and cover the following areas:

1. Intended readers – have you identified the different user types, for example, system operators, home users, and experts?

2. Have you identified the assumed level of experience and highlighted the sections of user guide which apply to them.

3. Software version – is the software release the User Guide refers to identified?

4. Purpose – have you described the purpose of the system and User Guide?

5. How to use User Guide document – have you described the intended use, section contents and relationship between sections?

6. Related documents – have you identified related documents?

7. Conventions – have you described symbols, conventions and syntax conventions used in the guide?

8. Problem reporting instructions – provided an email address so readers can contact you if they find an error or omission?

Overview

Have you outlined how the system works at a high level?

1. Identified key functions?

2. Inputs and Outputs – identified inputs what you, the reader, need to enter, and outputs, what you expect in response, for example, reports?

3. Provided further detailed explanation, if necessary.

4. Assumptions on user expertise, for example, experience or proficiency in related areas or previous training.

Procedures

This is usually the heart of the user guide. For each task, document the following:

1. Explain how to get started, for example, specific settings they need to make to use the application, such as installing a plugin or checking that a specific version of Java has been installed.

2. Describe the different functions of the system.

3. Provide cautions, warnings, and recommendations.

4. For each procedures, identify where in the application you perform this task, input operations and expected results. If necessary, include a screenshot that helps the reader understand the task. Avoid pointless eye candy screenshots.

5. Required parameters, optional parameters, default options and order/syntax

6. Provide examples

7. Identify known issue, likely errors, possible causes, and resolutions.

Reference

Have you identified and described all system capabilities, for example,

1. Describe the purpose of different buttons on the menu bars, what happens if they get greyed-out, how to change this, why this occurred, and how to reset window layout.

2. Describe the purpose of each field, identify mandatory settings, minimum or maximum settings, recommendations, and data input types.

Error Messages and Recovery Procedures

Have you identified and described all error messages and recovery procedures, for example,

1. Document all error messages.

2. Identify root cause.

3. Suggest recovery procedures

Glossary

Have you provided a list of ambiguous terms or terms users may not know to the reader.

Index

Have you provided an index? This is recommended for User Guides of 40 pages or more.

Document Control

Have you provided Document Control, Signoff and Change Record information?

PS – if you want the PDF to this, head over to my channel on SlideShare.

Posted on

Checklist: how to proofread technical documents in 15 minutes

You have fifteen minutes to check your technical document before it’s sent to the client. What do you do? Start at one page one and read every word out loud? Maybe, maybe not 🙂

Here’s one suggested approach to proofread any type of document when you’re under pressure.
276 Photos of Japan

Checklist: how to proofread technical documents in 15 minutes

Instead of reading the document in a single review, break it into a series of smaller, more focussed reviews:

  1. Time – give yourself a timeframe, say five minute blocks, then stop. Stretch, walk, and start again.
  2. Checklist – create a checklist of items you plan to review. These include the usual areas, such as spelling but also exceptions and known issues that tend to crop up. One example is language settings which may have changed if you pasted text in from another document. Another is different footers, again if you merged documents.
  3. Specific – check one area at a time, for instance, check the spelling, format, meaning, or structure individually. Don’t try to do all at once.
  4. Tables – make sure they have the correct heading, fit on the page correctly, and have a header column on the following page if they extend to the second page.
  5. Images 1 – check that the image is displayed correctly, for example, if it’s in an anchored frame in Adobe FrameMaker, check that the edges have not been cropped or positioned incorrectly in the frame.
  6. Images 2 – check that the image displays the correct screen, dialog box or component under discussion. It’s easy to import similar looking images especially if you are new to this area. Also, don’t automatically trust what’s in legacy documents to be correct.
  7. Crossreferences – check that cross-references link to the correct text. It’s easy to miss this especially if you test the link – and it works – but don’t check if it links to the correct text. Double-check that you’re cross-referencing to the correct section, and don’t assume existing cross-references are correct.
  8. Brand Names – create a checklist (cheat sheet) with the correct spelling for each product. Then check if these have been spelled correctly across the document set. For example, it’s Yahoo! not Yahoo, and IBM not I.B.M..
  9. Versions – if you’re updating a new document set, make sure that the version numbers for ALL affected products are updated if necessary.
  10. Variables – if you use variables in your documents, for example, in Adobe FrameMaker, check that these are correct and also check if these have been hard-coded by other writers. This can happen if a team writes different parts of the document and someone doesn’t know (and doesn’t ask) how to apply and update variables.
  11. Hardcoding – this is text that should not be hardcoded, for example, variables or conditional text but someone has hardcoded instead. One area to check is hardcoded links, i.e. a link to a specific page number rather than the actual page, which may change if text is added or deleted.

What else would you add?