Troubleshooting topic

Darwin Information Typing Architecture (DITA) Version 1.3 Part 3: All-Inclusive Edition

version
1.3
author
OASIS DITA Technical Committee

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

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>