Posted on

[Checklist] How to Review Troubleshooting Guides

troubleshooting-guide-review-checklist

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.

PS – Download your Troubleshooting Guide here.

Posted on

User Guide Checklist

This checklist summarizes the recommended structure and contents for User Guide documents.

teacher

Introduction

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

– Intended readers – identify the different user types, for example, system operators, home users, and experts. For each, identify the assumed level of experience and highlight the sections of user guide which apply to them.

– Software version – identify the software release the User Guide refers to.

– Purpose – describe the purpose of both the system and User Guide.

– How to use User Guide document – describe the intended use, section contents and relationship between sections.

– Related documents – identify any related documents.

– Conventions – describe symbols, conventions and syntax conventions used in the guide.

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

Overview

Outline how the system works at a high level.

– Identify the key functions

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

– Provide further detailed explanation, if necessary.

– 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:

– 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.

– Describe the different functions of the system.

– Provide cautions, warnings, and recommendations.

– 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.

– Required parameters, optional parameters, default options and order/syntax

– Provide examples

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

Reference

Identify and describe all system capabilities, for example,

– 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.

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

Error Messages and Recovery Procedures

– Document all error messages.

– Identify root cause.

– Suggest recovery procedures

Glossary

Provide list of ambiguous terms or terms users may not know to the reader.

Index

This is recommended for any User Guides of 40 pages or more.

Document Control

Ensure there is Document Control, Sign-off and Change Record information.

Document Structure

Ensure that the guide has the following:

– Headers, footers, navigation bars

– Table of contents

– Index

– Glossary with product terminology and industry terms

– Cross-references/links to related procedures/documents

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

– Is there adequate white space?

– Have you avoided large blocks of text?

– Does the document separate conceptual, procedures, and reference materials?

Visual Information

In addition to text information, provide 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:

– Headings

– Bullets

– Bold

– Arrows

– Illustrations

Different Learning Styles

Where possible, develop content that supports the following methods of learning:

– Visual

– Audio

– Touch

In addition, provide the following types of examples:

– Concrete examples

– Abstract concepts

Document Format

Produce 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:

– Size – remember to optimize the PDF before publishing.

– Online/print – prepare the document in both formats if necessary.

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

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

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

Posted on

Functional Specification Checklist

Writing the functional specification occurs after we’ve evaluated the product or technology. If we look at the project planning lifecycle, we can see it’s the second process:

  1. Evaluating products.
  2. Writing the functional specification.
  3. Packaging the master project plan.
  4. Creating the master schedule.
  5. Reviewing Project Plans.

Functional-Specification-Checklist

PS – you can download a Functional Specification Checklist template over here.

Functional Specification Checklist

Before we start writing this document, we need to ensure we understand and check the following:

1. Check if features were deleted from the vision/scope document.

2. Identify assumptions about the solution, customers, and users.

3. Identify dependencies the solution may have on other services, technologies, and people within the organization.

4. Plan how to address security.

5. Identify installation and un-installation requirements.

6. Identify integration requirements.

7. Understand the business case and business benefits.

8. Identify the solution’s high-level architecture.

9. Identify the solution’s components, including how they relate to other components.

10. Identify naming standards it must follow.

11. Identify security guidelines that the solution must follow.

Inputs

To write the Functional Specification, the following inputs are required:

1. Vision/scope document

2. Requirements documents, including:

3. Business requirements.

4. Operations requirements.

5. System requirements.

6. User requirements.

7. Product and technology evaluations

Outputs

After writing the Functional Specification, the following outputs are generated:

1. Design documents, including:

2. Conceptual design.

3. Logical design.

4. Physical design.

5. Functional specification

Best practices

1. Avoid scope creep.

2. Use the vision/scope document to integrate the business goals.

3. Trace features back to the original requirements.

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?