[This blog post was originally published on the IXIASOFT website on February 5, 2016. It is reproduced here with permission].
Troubleshooting has been around as long as humans have been tinkering with the gadgets they have created. I don’t doubt that the person who invented the wheel was given plenty of advice from others the first time it needed repairing. If you bought a Ford Model T back in the day, you would have found its manual sprinkled with troubleshooting information for various situations, such as what to do if the electrical system failed, the starter motor wouldn’t turn over, or what steps to take if steam started to appear from the radiator. Similarly, who doesn’t hate it when your smart phone won’t dial, your washing machine won’t wash, or some other gadget doesn’t perform the task for which it was designed. Even worse is not being able to find information on how to fix the problem.
Up until recently, DITA-based content creators were forced to awkwardly stuff this type of information into task topics, but with the advent of DITA 1.3 more options are now available. Two new troubleshooting elements were added to the task topic, a new troubleshooting note type now exists, and there is even a wholly new troubleshooting topic type as well.
The Basic Troubleshooting Pattern
The new troubleshooting additions to DITA 1.3 follow a common pattern designed to provide the type of information users are looking for when facing a problem. The trick to writing effective troubleshooting content is to follow these steps:
- Describe the problem condition
- Determine a possible cause
- Propose a remedy
That’s it. Strictly speaking, the new troubleshooting topic type is the only one of the troubleshooting additions to DITA 1.3 that models this pattern fully, but it is an accepted information pattern that is known to work. This sequence can be stripped down further to a more basic problem/resolution pair, which will do the job but adding a probable cause informs the reader as to the “why” of the situation and may tip them off to other possible solutions.
If you can keep these three steps in mind when writing troubleshooting content, it is hard to go wrong. In fact, Dr. Carlos Evia, Director of Professional and Technical Writing at Virginia Tech, discovered that his students “had a short learning curve for authoring troubleshooting topics”, and this was for people with little or no prior experience writing DITA. Once you learn how to write to the basic troubleshooting pattern, it is easy enough to do.
Troubleshooting Note
In DITA 1.3 the note element can now take the new @type attribute “trouble”. It is designed to provide the reader with information on how to solve an issue that may arise relating to the current context. For example, the following note might have been useful for the owner of a Model T who found that their car engine stopped suddenly while driving:
<note type="trouble">If your engine has sputtered and then stopped while driving, first check the fuel gauge. If the fuel gauge reads Empty, it is time to find some gasoline to put in the tank of your vehicle.</note>
This note is not trying to be comprehensive; instead it is simply providing a possible problem > cause > remedy that may arise when a user is driving their car. It is incidental (but important!) information that a new driver ought to know about when taking their new Model T out for a spin.
Troubleshooting in Task Topics
It has been common for DITA-based content creators to insert troubleshooting information into their task topics. This makes sense because it is the one place you can reliably expect to inform the reader about potential problems they may face within a procedure. With DITA 1.3, the new steptroubleshooting and tasktroubleshooting elements are available, instead of having to awkwardly shoehorn this information into a task topic. The steptroubleshooting element is used to describe troubleshooting within a step, and tasktroubleshooting is used for a problem that does not match the expected result of a task.
The steptroubleshooting element is designed for use in situations where something other than what is described in a stepresult occurs.
In the following example that is an excerpt of a longer procedure to start and then drive your Model T, steptroubleshooting is used to describe a possible error condition, its likely cause, and remedy:
<step>
<cmd>Take hold of the starting crank handle and push firmly toward
the car until you feel the crank ratchet engage, then lift
upward with a quick swing.</cmd>
<stepresult>
<p>The engine starts.</p>
</stepresult>
<steptroubleshooting>
<p>If the engine does not start, the mixture of gasoline to air
may not be rich enough, especially if the weather is cold.
Turn the carburetor dash adjustment one-quarter turn to the
left in order to allow a richer mixture of gasoline to be drawn
into the cylinders; then hold out the priming rod, while turning
the crank from six to eight one-quarter turns in quick
succession.</p>
</steptroubleshooting>
</step>
If a problem is more likely to be noticed at the end of a task, use the tasktroubleshooting element instead. It describes a problem that differs from the expected result. Here’s an example of this, applied to our Model T manual at the end of a task for replacing a faulty muffler:
<steps>
<step><cmd>...</cmd></step>
<! – ... previous steps for replacing the muffler ... – >
</steps>
<result>
<p>The newly installed muffler should greatly reduce any noise from the
gasoline exploding in the cylinders of the engine.</p>
</result>
<tasktroubleshooting>
<p>If there is still a lot of engine noise from your Model T after
installing a new muffler, check the following:
<ul>
<li>Check for any fresh damage to the newly installed muffler.</li>
<li>Ensure that the pack nuts and bolts connecting the muffler to
the exhaust pipe are tight.</li>
<li>Look for holes in the exhaust pipe between the engine and the
muffler.</li>
</ul>
</p>
</tasktroubleshooting>
Notice that it is possible to insert both paragraph tags, as well as unordered list elements. The tasktroubleshooting element is specialized from section, so it can hold most other elements you are likely to need. If there are additional remedies available for a given situation that are more complex, create a new troubleshooting topic for them and simply add a link to it.
The Troubleshooting Topic Type
The new DITA 1.3 troubleshooting topic type is designed to cover a situation more comprehensively than can be covered by a simple troubleshooting note or by troubleshooting sections within a task topic. When writing a troubleshooting topic, keep in mind that a user has likely turned to it in order to fix a problem, so be clear and succinct.
Troubleshooting topics begin with the description of a problem a user may encounter, followed by one or more causes and their associated remedies.
Here is an example of a troubleshooting topic for our Model T manual that describes a particular condition, and then examines two possible remedies for it:
<troubleshooting>
<title>Car Misfires When Traveling at Low Speeds</title>
<shortdesc>Situations that may cause the Model T to misfire and how to
resolve them.</shortdesc>
<prolog>
<metadata>
<keywords>
<indexterm>misfire</indexterm>
<indexterm>backfire</indexterm>
</keywords>
</metadata>
</prolog>
<troublebody>
<condition>
<p>While driving at relatively low speeds the Model T begins to
misfire.</p>
</condition>
<troubleSolution>
<cause>
<p>A rich mixture of too much gasoline and not enough air.</p>
</cause>
<remedy>
<steps>
<step>
<cmd>While the engine is running, adjust the needle valve
regulator on the dash counter-clockwise until the motor
runs steadily.</cmd>
</step>
</steps>
</remedy>
</troubleSolution>
<troubleSolution>
<cause>
<p>A spark plug has ceased to work properly.</p>
</cause>
<remedy>
<steps>
<step>
<cmd>Turn off the engine. Exit the car and open the engine
hood.</cmd>
</step>
<step>
<cmd>Inspect the electrical connections to ensure that they
are not damaged or disconnected from each spark plug.
If the wiring appears to be fine, go to the next step.
</cmd>
</step>
<step>
<cmd>Look for cracks in the insulation of each spark plug.
If damage is found, first disconnect the suspect spark
plug from the electrical system and then replace it. If
this is not the case, proceed to the next step.</cmd>
</step>
<step>
<cmd>Remove each spark plug in turn from the engine. Clean
any carbon that has built up on the spark gap, and then
re-insert the spark plug into the engine.</cmd>
</step>
</steps>
</remedy>
</troubleSolution>
</troublebody>
</troubleshooting>
While the new DITA 1.3 troubleshooting topic type looks superficially like a task topic, it is inherited from the more generic topic type and is different in its construction. The troubleshooting element that defines the topic type comes after the usual XML declaration and reference to the DITA 1.3 DTD (omitted in this example), followed by the title and (in this example) the optional shortdesc and prolog elements. While optional, a good short description can help the reader determine whether the troubleshooting topic will help them, and it is recommended that the prolog contain relevant indexterms that will aid the user to find the topic (though not depicted in this example, the troubleshooting topic can also take the optional titlealts, abstract and related-links elements). The condition element—which describes the problem that the user is facing in full—sets the stage for the remedy or remedies to come. The condition element is optional, and can be omitted as long as both the title and the shortdesc for the topic adequately describes the situation.
After that comes one or more troubleSolution sections, each providing a description of a possible cause for the problem, followed by a stepwise procedure for resolving it. The cause element describes a possible source for the problem, and should be brief and to the point. The remedy section comes next, which can contain an optional responsibleParty element (not present in the example code), which is used to name the role of the person who is qualified to fix this problem scenario. For most scenarios, the responsibleParty will be unambiguously implicit, and so can be left unspecified. This is because separate publications are usually prepared for different audiences, so if you are creating content for different responsible parties, you may just want to use the audience attribute for conditional processing of the content at output instead.
Both cause and remedy are optional and repeatable, so it is possible to omit one or the other, or to have more than one cause and remedy. While both troubleSolution sections in this example use the same steps / step / cmd element sequence, the steps-informal and step-unordered elements can also be used within troubleSolution. Unlike a task topic, there are no optional result, example or postreq elements available.
As always, keep reuse possibilities in mind and consider using conrefs for things like step sequences that are the same between topics. Conref-ing whole troubleSolution blocks of content is likely to become common practice. For example, it may make sense to store a commonly-used troubleSolution content block in a “library” or referable-content topic (the latter a specialized topic designed for this purpose in the IXIASOFT DITA CMS) that has instructions for contacting support.
By the end of the troubleshooting topic the reader ought to have solved the problem they encountered, so it is important to make sure that you have covered the most likely issues a user is to encounter—don’t leave them wanting more!
For more on the subject of DITA 1.3 troubleshooting, take a look at the following articles/references:
- Bob Thomas’ excellent DITA Adoption Committee article: Using DITA 1.3 Troubleshooting
- Carlos Evia’s terrific piece called Taking the DITA troubleshooting topic for a spin
- Read the section on the new troubleshooting topic and its associated tags in the official DITA 1.3 specification
A big thank you to Bob Thomas, Owner of Tagsmiths, LLC for doing a technical edit of this article.
