Writing troubleshooting topics

It’s a fair bet that the introduction of the new Troubleshooting information type into the DITA 1.3 technical authoring standard will affect how all Technical Authors write troubleshooting topics, regardless of whether they use DITA or not. That’s because the proposed elements for troubleshooting topics make good sense, and it offers a standardised approach to writing these types of topics.

According to the Oasis DITA standards committee,

Troubleshooting topics provide descriptions of and solutions or workarounds for problem situations that users might encounter. Users refer to troubleshooting information to understand what condition or event generated their problem situation and to find out what they need to do to recover from or work around a problem, or to prevent a recurrence of the problem.

The user would see a topic that looks roughly like this:


Application is not responding

Overview

This topic explains what to do if the application is not responding to your keyboard or mouse.

The problem

The application does not respond to input from the keyboard or the mouse.

The cause

The application has entered into a state from which it cannot recover.

Remedy

  1. Right-click on the Windows task bar and select Task Manager.
  2. Right-click on the application and select End Task.

The application should now respond correctly. If it does not, please contact the Support desk.

Responsible party

Users must fix this problem.

Related topics

See also:

  • Adding a widget

You’ll notice there are a set of common headings:

Section Description Example
Topic Title A brief statement of the problem. Application is not responding.
Overview/Introduction A fuller explanation of the purpose of the procedure and when you would use it. This topic explains what to do if the application is not responding to your keyboard or mouse.
Condition (the problem) Usually the condition or symptom is an undesirable state in a system, a product, or a
service that a reader may wish to correct.
The application does not respond to input from the keyboard or the mouse.
Cause A cause for the condition or symptom. The application has entered into a state from which it cannot recover
Remedy (Solution) A remedy for the condition or symptom that restores the system, product, or service to its normal state.The step-by-step instructions that explain how to actually do the procedure.Steps begin with an action statement that tells the user what to do. Every action statement contains a “command” verb.A step may also contain a feedback statement. This tells the user what happens as a result of completing the step.
  1. Right-click on the Windows task bar and select
    Task Manager.
  2. Right-click on the application and select
    End Task.
Responsible Party Who is expected to perform the steps in the remedy. Users must fix this problem.
See also  Links to related topics. See also:

Adding a widget

We think the proposed structure is good, and it’s worth adopting. What do you think?

4 thoughts on “Writing troubleshooting topics

  1. Re. Overview/Introduction
    IMHO too generic. May invite tech authors to write long stories or repeat the title.

    Proposed solution: “Short Description”. Dita authors are familiar with Short Desc and guidelines for writing _good, meaningful_ Short Descriptions are available (s. Kirsten Eberlein and Michelle Carey)

  2. You’re right that writers following DITA 1.3 standard will use ShortDesc instead of Overview or Introduction.

    For writers not using DITA, and for users, both of whom are unlikely to understand the phrase Short Description, Overview or Introduction is probably a more meaningful phrase to use.

  3. You have necessarily used a simple example with a single symptom and a single solution. I wonder how well it will work for a less well defined problem like “The system is slow to respond” or “Some of my messages don’t always get delivered”, where some real investigation is required to pin down exactly what has gone wrong and what course or courses of action are likely to alleviate the problem. I guess that will depend to some extent on how flexible the “Remedy” element is. From the example it looks as if it contains , so it probably also allows , but will it allow generic text in or tags?

  4. In the scenario you posed, it would probably be better to use the concept information type, perhaps linked to other to tasks or a list of potential troubleshooting remedies.

Leave a Reply

Your email address will not be published. Required fields are marked *

CAPTCHA Image

*

You may use these HTML tags and attributes: <a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <strike> <strong>

Notify me of followup comments via e-mail. You can also subscribe without commenting.