One of the results of good technical documentation is reducing calls to your product’s help desk. DITA 1.3 has added new features to help you create better troubleshooting topics. Let’s take a look at them.
The “trouble” value
The new DITA 1.3 spec has added a new value, “trouble”, for the @type attribute of the <note> element. This allows you to provide information within any topic type on how to deal with a possible error or malfunction. In previous versions of a spec, you could use the “important” or “tip” value. The “trouble” value allows you to bring a more specific reason why you would want to draw attention to the note. Here’s an example of how you would code it:
<steptroubleshooting> element
The <steptroubleshooting> element is used in task topics. This
element is used to explain what to do if the result of the step does not
match the results documented in the <stepresult> element.
To see how it would be used, take a look at this sample from the DITA 1.3 spec.
<tasktroubleshooting> element
The <tasktroublehooting> element is also used in task topics. This
element differs from the <steptroubleshooting> element in that it
follows the <result> element. That is, where
<steptroubleshooting> explains how to remedy the results of a
single step, <tasktroubleshooting> helps when the results of a
series of steps are unexpected.
To see how it would be used, take a look at this sample from the DITA 1.3 spec.
The troubleshooting topic
The Troubleshooting additions to DITA 1.3 are designed to overcome the obstacles and make it easier for users to identify problem-solving information.
You may ask, “Haven’t we had a troublehooting topic for a while?” Yes and no. A troubleshooting specialization was developed for the DITA OpenToolkit in 2007. It had relatively simple sections such as Symptoms, Causes, Diagnoses, and Resolve. DITA 1.3 formalizes troubleshooting into a new topic.
As a topic-level element, <troubleshooting> contains elements such as <title>, <shortdesc>, <related-links>, etc. <troublebody> is the main body element in a troubleshooting topic. The <troublebody> element contains the following elements:
<condition>
Describes a condition or symptom that is associated with an undesirable
state in a system, a product, or a service. This is an optional element.
<troubleSolution>
Required. This element contains the <cause> and <remedy>
elements. The elements are for text describing the possible reasons and
solutions for the problem. The <remedy> element begins with an
optional <title> element followed by an optional
<responsibleParty> element followed by either a <steps>
element, a <steps-unordered> element, or a <steps-informal>
element. The <responsibleParty> element indicates who is expected
to perform the steps that are outlined in the remedy.
Summary
The new troubleshooting features in DITA 1.3 will be an important
resource for writers who want to get users accurate and helpful
information. It will also help prove the value of the writing group when
you are able to reduce calls to the product help desk.
Note: You can find the DITA 1.3 spec here.
Related janacorp.com Blog Entries:
DITA 1.3 is 3 in 1
A Celebratory Year for DITA
DITA 1.3 is on the way!
Related janacorp.com Webinars:
Why DITA? Workshop
DITA Workf
