DITA 1.3 Troubleshooting Topic Type Feature in oXygen 15.2

DITA 1.3 Troubleshooting Feature in oXygen 15.2
DITA 1.3 Troubleshooting 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.

About

"DITAWriter" is Keith Schengili-Roberts. I work for AMD as a Senior Manager for Technical Documentation, and have recently helped usher in a new company-wide DITA-based CCMS. And I like to write about DITA and the technical writing community. To get ahold of me you can email me at: keith@ditawriter.com.

View all posts by

2 thoughts on “DITA 1.3 Troubleshooting Topic Type Feature in oXygen 15.2

  1. Thanks for the review. Actually, troubleshooting is an entirely new topic type, not based on task. It was developed by the DITA Technical Communication Subcommittee with lots of testing and examples. The chief author of the new topic, Bob Thomas, is currently working on a Feature Article that we will publish through OASIS. One of the new function is the ability to use inside a new topic type. Making into a reusable domain is an important addition to DITA 1.3 and enabled this new topic type.

    The new troubleshooting topic allows you to provide more than one set of steps, which is common when there is more than one way to fix a problem. In the task topic, only one set of steps is allowed. It also means that you can reuse a set of steps from a task in the troubleshooting topic, a huge advantage if you want to increase your reuse of key content and avoid having to update in multiple locations.

    At the subcommittee, we are excited about this new topic type, having been working on it for a year. It all started with a request from organizations that needed it. That’s how everything gets started.

Comments are closed.