Troubleshooting information

Troubleshooting information is invaluable to technical content users because it provides advice to correct problems with task performance.

User studies show that users find troubleshooting information invaluable because they frequently access technical information only when they have encountered a problem in performing a task.

The DITA troubleshooting elements added in DITA 1.3 encourage authors to provide troubleshooting information directly within a task, at the point of need, and to label the troubleshooting information appropriately. Minimalism research indicates that users are most likely to read troubleshooting information if it is visibly labeled. We recommend that implementations use style sheets that add symbols or text to draw attention to the troubleshooting elements in the topics.

Troubleshooting information can be added to an individual step in a DITA task; it also can be added after the steps are completed. Troubleshooting information can be added in any topic type in a <note> element with the @type attribute set to "trouble". However, we recommend that users use either <steptroubleshooting> or <tasktroubleshooting> when working on a task topic, rather than inserting an <note> element with the @type attribute set to "trouble".

The examples below illustrate the three options.

Step troubleshooting

Troubleshooting information can be added following a step in a procedure if it is likely that the user will encounter a problem in performing the step.

The <steptroubleshooting> element can occur following the <cmd> element in the <step> or <substep> element. The <steptroubleshooting>element ends the <step> or <substep> element. Another element, such as <info> or <stepxmp>, cannot be added after the <steptroubleshooting> element.

The first example shows troubleshooting information added to a step. The second example shows the troubleshooting information following a step result.

<step>
    <cmd>Select <uicontrol>Shut Down</uicontrol> from the
         <uicontrol>File</uicontrol> Menu.</cmd>
    <steptroubleshooting>If a problem with the computer prevents you from choosing 
          Shut Down—for example, if the computer freezes so that the pointer does 
          not respond to the trackpad—you can turn off the computer by holding down 
          the Control, Option, Command, and Power On keys at the same time.
    </steptroubleshooting>
</step>

<step>
    <cmd>Select the element for which you want to assign a conditional-
         processing attribute, and, in the <wintitle>Attributes</wintitle>
         window, select the conditional-processing attribute.</cmd>
    <stepresult>The permissible values for the attribute are displayed in a
                drop-down list.
    </stepresult>
    <steptroubleshooting>If the list of controlled values is not displayed, 
                         ensure that the root map is opened in the
                         <wintitle>DITA Maps Manager</wintitle> window.
    </steptroubleshooting>
</step>

Task troubleshooting

Troubleshooting information can be added after the procedural component to assist the user in correcting a problem that might have occurred. The <tasktroubleshooting> element is one of four optional elements that can follow the <steps> element. When these optional element are used, they must appear in the following order: <results>, <tasktroubleshooting>, <example>, and <postreq>.

<steps>
    <step>
        <cmd>When the fast blinking stops, press
             <uicontrol>small espresso</uicontrol>.</cmd>
    </step>
</steps>
<tasktroubleshooting>If the <uicontrol>small espresso</uicontrol>
                     button is not lit, recycle the unit by turning 
                     the external <uicontrol>Power</uicontrol> off 
                     and on.
</tasktroubleshooting>

Troubleshooting note

A <note> element can include type="trouble" to indicate that the note deals with a potential problem that the user might encounter. We recommend that DITA implementations configure their CSS or stylesheets to include appropriate text or an icon in the generated output.

Best practices for authoring DITA content mandate that the troubleshooting note should not be used in place of <steptroubleshooting> or <tasktroubleshooting> in a task topic.

<concept>
    <p>If you expose your camera to sudden changes in temperature or
       humidity, you might experience some condensation in the camera.
       Aavoid the possibility of condensation because it might
       result in soil on the lens or the monitor, cause mold, or damage
       the camera.</p>
    <note type="trouble">If you do get condensation, turn off the camera 
                         and wait about two hours before using it. Once 
                         the camera adjusts to the surrounding temperature, 
                         the fogging will clear naturally.
    </note>
    <!-- ... -->
</concept>