Technical Writing

[Checklist] How to Review Troubleshooting Guides

Posted on by Fionn

Making a list, checking it twice… or three times…

How do you test your Troubleshooting Guide after you write it? One way is to create a checklist and test each part individually.

This also helps System Administrators and Software Testers to double-check that all procedures have been completed correctly.

Ok, less talk from me. Let’s take a look.

Use the If/Then Format

Phrase the checklist items using questions, if/then statements, and notes.

For example:

Ask the question:

  • Is the core running?
  • On Windows, check for the appropriate service name.
  • On Linux, check for the appropriate daemon name.

Describe how to verify this is correct, for example,

‘Use the sysmgr command to verify that the System Manager is active.’

Other examples of questions and verification steps:

  • Was synchronization started from the console or the command line?
  • Are the directory sources currently running? Use the console to verify that modifications synchronized in the expected direction.
  • If synchronizing users in one directory source, were these users created in the other directory source using the sync command?

Add Explanatory Notes

In some cases, you need to provide additional information to help the reader understand the underlying problem. For example:

If this was not true, describe what the Sys Admin should do, for example:

Run the sync command whenever there are existing users.

Then add an explanatory note:

Note: If you do not update existing users, accounts information will conflict.

Checklist using If-Then-Verify Procedure

Use if-then-verify checklists to test technical documents.

This works as follows:

  1. If an error occurs
  2. Then do this to check it.
  3. Verify that is works by doing the following

For example:

  1. If the user account is not replicated from the Active Directory to the Directory Server,
  2. verify that all mandatory attributes in the Directory Server are specified.

Checklist using If But Verify

In this example, one process succeeded, but a second failed.

  1. If synchronizing is replicated to the Directory Server and the user creation succeeded,
  2. but the account is unusable,
  3. verify that the user name is valid.

Provide additional information for the user to resolve the issue:

For example, if you specify an account that exceeds the maximum allowable length, the account will be created but cannot be used until you rename it.

Download Troubleshooting Guide Template

PS – Download your Troubleshooting Guide here.

Fionn