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 steptroubleshootingelement 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.
Parent topic
Related concepts