The troubleshooting information type
In its simplest form, troubleshooting information follows this pattern:
- A condition or symptom. Usually the condition or symptom is an undesirable state
in a system, a product, or a service that a reader wants to correct.
- A cause for the condition or symptom.
- A remedy for the condition or symptom.
The troubleshooting topic provides sections for describing the condition, causes, and
remedies needed to restore a system, a product, or a service to normal.
For some conditions there could be more than one cause-remedy pair. The
troubleshooting topic accommodates this. Typically, a cause is immediately followed
by its remedy. Multiple cause-remedy pairs can provide a series of successive
fall-backs for resolving a condition.
Cause and remedy might occur in combinations other than pairs. It is possible to
have:
- Multiple causes with the same remedy
- A single cause with more than one remedy
- A remedy with no known cause
- A cause with no known remedy
The troubleshooting information type also can be used to document alarm clearing
strategies.
The structure of the troubleshooting topic
The top-level element for troubleshooting topics is
troubleshooting. The
troubleshooting element contains a
title with optional alternative titles
(titlealts), a short description or
abstract, a prolog, a
troublebody, and
related-links.
troublebody is the main body element in a troubleshooting
topic. The troublebody element contains the following
elements:
- condition
- This optional element is the first child of troublebody, and it
describes a condition or symptom that is associated with an undesirable
state in a system, a product, or a service. In cases where the topic title
fully explains the condition, do not use this
element.
- troubleSolution
- One or more troubleSolution elements must appear in the
troublebody element.
troubleSolution is a wrapper element for
cause and remedy, each
of which are a cause-remedy pair.
The troubleSolution element contains the following elements:
- cause
- This optional, repeatable, first-child ofcondition
troubleSolution describes a possible cause for the
condition.
- remedy
-
This optional, repeatable, last-child of
troubleSolution describes a possible remedy
for the condition.
The remedy element begins with an optional
title element followed by an optional
responsibleParty element followed by either
a steps element, a
steps-unordered element, or a
steps-informal element. The content models
for steps,
steps-unordered, and
steps-informal are borrowed from
task. This allows remedy to reuse steps
from tasks.
- <responsibleParty>
- This optional first child of remedy indicates who
is expected to perform the steps that are outlined in the
remedy element.