2.7.3 Troubleshooting information

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>