Are you using the DITA 1.3 troubleshooting topic? #troubleshooting

Kristen James Eberlein

I'm curious; how many companies and implementations are using the DITA 1.3 troubleshooting topic?

The troubleshooting topic arrived with DITA 1.3; it was championed by the DITA Technical Communication subcommittee and much of the work was done by Bob Thomas, Tagsmiths.

There is an excellent white paper that Bob authored for the DITA Adoption TC:

Anyhow, who is using the troubleshooting topic? Are there things that work for you? Things that don't work for you?

For DITA 2.0 we (the DITA TC) are looking at the following enhancements:

  • A diagnostic element
  • Allowing <draft-comment> as an option child of <remedy>

Kristen James Eberlein
Chair, OASIS DITA Technical Committee
Principal consultant, Eberlein Consulting
+1 919 622-1501; kriseberlein (skype)

Larry Kollar

We use it. We have several templates for it, depending on the complexity of the troubleshooting topic. Mine generally use one cause/remedy pair, but there are a few that use multiple troubleSolution.

We also support an @outputclass called "message" that makes minor tweaks to the output to support documenting syslog messages and the like. My thought was, the message itself is the condition, which has a cause and (maybe) an associated action. It works pretty well for that.

David Yin

We are using the Troubleshooting topic.  I believe I spoke to Bob back in 2017 about wanting to start using it.


I like the new topic type since it clearly identifies itself as separate from a procedure or a task.


The challenges we have are not directly related to the troubleshooting topic.  The issues are split between a pdf output style and DITA reuse strategy.


To your questions:

  • Diagnostic elements would be a good use; but you would need to define this structure really well or it will be useless.
  • Draft comments, I am surprised that it is restricted today.  I suppose we use <comments> instead.



David Yin

Technical Publication Manager  |  david.yin@...  |  940.591.4196