I've been working on a Troubleshooting feature article for the DITA Adoption TC. It's nearly complete except for a scenario that describes dealing with complex troubleshooting scenarios. Here is the text from the article that sets the context for the complex scenario (the highlighted text is important for what I want to say about the content model):
For my scenario, I want to use a DITA map having a troubleshooting topic serve as a wrapper around sub-topics that help the user determine a cause and go to its remedy. This means that the outer troubleshooting topic needs to have a condition where the product-reported condition is discussed, but nothing after it because the cause/remedy information will come from subordinate topics.ComplexitySoftware products are often complex. Fortunately, when things go wrong within a product, good software engineering shields users from most of this complexity. But, in some cases, there simply is not enough development budget to cover every eventuality with code. Unfortunately, if the code does not supply the intelligence for recovering from a problem, the responsibility falls to the product documentation. Failing that, the responsibility cedes to technical support. And finally, failing that, the responsibility lands upon the user or upon a user community. For our purposes, we will assume that the product documentation has accepted its responsibility.
Resolving complex problemsRegardless of complexity, the basics of the troubleshooting information type are still valid: condition, cause, remedy. However, complexity manifests itself almost immediately. Typically, the condition the product reports is too general, making it unlikely that the user will be able to immediately identify the actual cause. This becomes problematic in troubleshooting scenarios where the user cannot simply try one remedy after the next. For some products, that method is too disruptive, and it may be unsafe. The cure for this is to use diagnostic procedures to further explore the condition until it points to a single cause. Once the cause has been isolated, a suitable remedy can be followed.
Unfortunately, the content model for troublebody is (condition?, troubleSolution+). It needs to be (condition?, troubleSolution*) to allow a troubleshooting topic to serve as a wrapper.
I don't know whether we can make this change, but we certainly ought to do it if we can.
Best Regards,
--
Bob Thomas
![]()
Bob Thomas
+1 720 201 8260
Skype: bob.thomas.colorado
Instant messaging: Gmail chat (bob.thomas@tagsmiths.com) or Skype
Time zone: Mountain (GMT-7)