Sunday, March 27, 2016

Looking for trouble with DITA 1.3



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> elements 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.

No comments:

Post a Comment