Glossary · Information types

DITA troubleshooting topic

Also known as: troubleshooting, troubleshooting topic

In DITA 1.3, a troubleshooting topic is a topic type for problem-solving information: it describes a condition (the symptom a reader observes), one or more possible causes and, for each cause, a remedy. Its body element is <troublebody>.

DITA
Information typing
New in DITA 1.3

In one sentence

The DITA 1.3 troubleshooting topic pairs a symptom (condition) with possible causes and a remedy for each.

Example

The troubleshooting topic “No air flow” with the condition “The fan runs, but no air comes out” and two solutions: clogged filter (replace it) and blocked grille (clean it).

Explained in context

Context cards connect this term with others to answer one question. Also in British English and German.

Human error types and troubleshooting: from slips, lapses and mistakes to recovery informationTransitional topicHow do the error types of James Reason and Jens Rasmussen's skill-, rule- and knowledge-based behavior help design troubleshooting and recovery information?UK Deutsch

How it applies

Technical documentation: The troubleshooting topic, new in DITA 1.3, replaces the error tables many teams built by hand. Its body (<troublebody>) starts with a <condition> and continues with one or more <troubleSolution> elements, each pairing a <cause> with a <remedy>.
Service: A remedy can name who may perform it (<responsibleParty>) and contain steps, so a fix that needs a trained technician is marked as such.
Related additions: DITA 1.3 also added <steptroubleshooting> and <tasktroubleshooting> to tasks and the note type trouble, for short troubleshooting information inside other topics.
AI and retrieval: The condition–cause–remedy structure maps directly onto diagnostic questions (“The device does not start — why?”) and lets an assistant present possible causes in order instead of guessing.

Troubleshooting topic vs. task

A task starts from a goal. A troubleshooting topic starts from a symptom and can offer several alternative solutions, of which the reader applies the one whose cause matches.

In DITA markup

<troubleshooting id="no-airflow">
  <title>No air flow</title>
  <troublebody>
    <condition><p>The fan runs, but no air comes out.</p></condition>
    <troubleSolution>
      <cause><p>The air filter is clogged.</p></cause>
      <remedy><steps><step><cmd>Replace the air filter.</cmd></step></steps></remedy>
    </troubleSolution>
  </troublebody>
</troubleshooting>