Troubleshooting topic

The troubleshooting topic type provides markup for corrective action information such as troubleshooting and alarm clearing.

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.

Here is an example of a troubleshooting topic: 

<troubleshooting id="nologon">
  <title>Cannot log on</title>
  <shortdesc>Login attempts have failed</shortdesc>
  <troublebody>
    <condition>
      <p>The system does not accept your login credentials.</p>
    </condition>
    <troubleSolution>
      <cause>
        <p>The CapsLock key might be on.</p>
      </cause>
      <remedy><steps-unordered>
        <step>
          <cmd>Verify that the CapsLock key is off.</cmd>
        </step>
      </steps-unordered>
      </remedy>
    </troubleSolution>
    <troubleSolution>
      <cause>
        <title>Wrong password</title>
        <p>The password that you are using does not match the one
          that is stored in the system.</p>
      </cause>
      <remedy id="gotoaccountmanagement">
        <steps>
          <step>
            <cmd>Open a Web browser window</cmd>
          </step>
          <step>
            <cmd>Go to
              <xref href="http://itdept.example.com/reset.html"
                format="html" scope="external">
                Account management</xref>, and follow the
              instructions</cmd>
          </step>
        </steps>
      </remedy>
    </troubleSolution>
    <troubleSolution>
      <cause>
        <title>Unknown account name</title>
        <p>The account name you are using does not match the one
          stored in the system.</p>
      </cause>
      <remedy conref="#nologon/gotoaccountmanagement"/>
    </troubleSolution>
    <troubleSolution>
      <remedy>
        <title>Still cannot log on</title>
        <steps-informal>
          <p>If none of the previous solutions work,
            consider asking for help. Contact your system
            administrator if your organization has one; otherwise,
            contact our support team.</p>
        </steps-informal>
      </remedy>
    </troubleSolution>
  </troublebody>
</troubleshooting>