Troubleshooting topic

The troubleshooting information type

In its simplest form, troubleshooting information follows this pattern:

1. 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.
2. A cause for the condition or symptom.
3. 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 of<condition> <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.