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

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