While working on a feature article for the DITA Adoption SC that discusses troubleshooting for DITA 1.3, I realized that the content model for the <condition>, <cause>, and <remedy> elements must allow an optional <title> element at their beginning. The current models omit <title> and rely upon stylesheets to supply labels for these elements. In the following paragraphs I make a case for using the <title> element for labeling instead of relying upon stylesheets.
The stylesheet-supplied, string method is sufficient for troubleshooting topics that contain a single cause-remedy pair (simple troubleshooting topics). But, in topics that contain two or more cause-remedy pairs (complex troubleshooting topics), the author is left with no good way to label the pairs so that the reader can easily distinguish them from each other. For complex troubleshooting topics, the labels for the causes need to indicate the nature of each cause.
The <remedy> element also needs <title> whenever remedy appears without an associated cause. For example, a common final fallback in a complex troubleshooting topic would be a stand-alone remedy such as this:
<troubleSolution>
<remedy>
<title>Contact technical support</title>
<steps-unordered>
<step><cmd>Contact technical support at either support@foo.com or 800-555-1234</cmd></step>
</steps-unordered>
</remedy>
</troubleSolution>
As for <title> in <condition>, allowing it would make troubleshooting easier to use for related remedial information such alarms, events, and errors. For example:
<troubleshooting>
<title>ALM934</title>
<troublebody>
<condition>
<title>Severity</title>
<p>Minor</p>
</condition>
<troubleSolution>
<cause>...</cause>
<remedy>...</remedy>
</troubleSolution>
</troublebody>
</troubleshooting>
In another alarm scenario, an organization may wish to use <condition> to present things the reader ought to consider before proceeding. In this case, they would have:
<condition>
<title>Considerations</title>
...
Adding optional <title> to <condition> would also facilitate specialization.
Therefore, the <condition>, <cause>, and <remedy> elements ought to allow <title> at their beginning. I would like for the titles to be optional so that implementers could use constraints to remove them from the content models. That would allow the current stylesheet-generated label implementation to be put in place by those organizations that want it.
There are no inheritance issues with this change. The <condition>, <cause>, and <remedy> elements would still inherit from <section>. Because <section> allows <title>, this would not be an issue. I have attached a modified version of troubleshooting.mod that shows exact implementation that I am proposing. Lines 83-87 and line 193 are the only modifications.
Bob Thomas