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