DITA 1.3 Troubleshooting Topic Type Feature in oXygen 15.2

Just over a week ago the people at Syncro Soft updated their oXygen XML Editor to version 15.2. What just caught my eye is the fact that there is already a DITA 1.3-specific feature added to the software, in anticipation of its release.

Yup, DITA 1.3. Just when you think you’ve got your head around DITA 1.2, the next version is imminent.

How imminent? Well, nobody is saying anything definite about this, but the agenda for the upcoming DITA North America conference lists the OASIS DITA Technical Committee Chairperson’s Kristen Eberlein‘s talk “Overview of DITA 1.3” among the first open sessions the morning of Day One of that conference, so we can expect to find out considerably more then. (Am currently working on an interview with her about DITA 1.3, so look for that as well!)

oXygen has a well-deserved reputation as being ahead of the game when it comes to DITA, it being among the first to include significant updates and convenience features prior to the release of DITA 1.2. They are evidently doing the same with DITA 1.3.

The key addition with this update is the introduction of the forthcoming Troubleshooting specialization, which debuts as a new topic type. Support for this is also included in a new DITA-OT test plugin on GitHub. From its sample code, the new troubleshooting topic appears to be a variant of the task topic type. The following is my stab at it, based on the sample code that can be seen on GitHub.

<?xml version=”1.0″ encoding=”utf-8″?>
<!DOCTYPE troubleshooting PUBLIC “-//OASIS//DTD DITA Troubleshooting//EN”
“../dtd/troubleshooting.dtd”>
<troubleshooting id=”resolve” xml:lang=”en-us”>
<title>Sample Troubleshooting Topic</title>
<shortdesc>Fixing your grammelgromit using doopful when the gronk is fused with the tubiform.</shortdesc>
<troublebody>
<condition>
<p>Gronk is fused with the tubiform on a Model XIII Grammelgromit.</p>
</condition>
<troubleSolution>
<cause><title>Gronk does not rotate or slide</title>
<p>Normally the gronk is able to glide smoothly within the tubiform, but there are some occasions where it gets stuck or even fused with the tubiform, usually due to extreme cold.</p>
</cause>
<remedy>
<steps>
<step>
<cmd>Inspect the gronk for ice. </cmd>
</step>
<step>
<cmd>Apply a warm hoopfuldorf for at least five minutes.</cmd>
</step>
</steps>
</remedy>
</troubleSolution>
</troublebody>
</troubleshooting>

As you can see, very similar to the structure of a typical task topic, and introducing the new tags <troublebody>, (think <taskbody>) <condition>, (similar to <context>?) <troubleSolution>, <cause> and <remedy> which appear to be semantic wrappers for the already-familiar <steps> and <step> that they enclose. While this is not something that everybody will need for their documentation, I can see how it may become a welcome addition for those who are seeking more directed help content aimed at solving user’s particular situations. It looks intriguing, though I would like to see a more robust example so that I can better understand the circumstances in which this could be used instead of a standard task topic. (A hint can be found from the publicly-available staging area for DITA 1.3, which references at least one additional troubleshooting tag which would clearly make it more distinct from the existing task topic type: <responsibleParty>).

If you have the latest version of oXygen, you can play around and validate your sample code using this new topic type. More information on it and the other features included can be found on its “What’s New” page,

Change is coming, and it is DITA 1.3! Nice to see that at least one vendor is already on top of it and providing their customers with a chance to better understand it prior to its release.