DITA 1.3 proposed feature 13096
Proposal to add a new element to support a troubleshooting section between the
<result> and <example> elements in a task topic.
Date and version information
Include the following information:
- Final draft of proposal completed on 6/2/2012 for TC vote 6/3.
- Champion of the proposal: DITA Technical Communications Subcommittee
There is often a need to include a troubleshooting section in a task, between the <result>
and <example>. The purpose of this section is to help the reader resolve any problems that
may arise should their result not match the result stated in the <result> section of the
task. It is expected the reader would need this problem-solving information after reading the
<result> section, since their is no sense in moving forward if the expected result was not
Add a new element named <tasktroubleshooting> to task topics that could be added after
<result> and before <example>.
The new tasktroubleshooting element, like <result>, will have the same content model as
<section> except that <title> will not be permitted.
- This addition will benefit writers who want to provide important troubleshooting information
within the task topic to aid users and have it clearly identified as troubleshooting
- This enhancement will have a significant impact because key troubleshooting information will
be provided at the end of the topic if the desired result is not achieved and will allow the
user to take the proper corrective action before moving on.
- Providing a semantic construct for this information, that appears in the same part of
structure, will improve consistency across tasks.
Provide a detailed description of how the solution will work. Be sure to include the following
- DTD and Schema modifications
- Topic or map specialization
- The strict Task constraints domain must be edited to allow the new element.
- A new element “tasktroubleshooting” would have to be added. The content model for
<taskbody> would be:
( ( (prereq) or (context) or (section) ) (any number)
then ( (steps or steps-unordered or steps-informal) ) (optional) then (result)
(optional) then (tasktroubleshooting) (optional) then (example) (any number) then
(postreq) (any number) )
- Inherit same attribute definition as specialization base ("section").
- Processing impact
- Processors may apply a label to content in this element to distinguish "Troubleshooting"
information from other content.
- Overall usability
This proposal would improve usability more than damage it.
- The presence of tasktroubleshooting in the task content model will prompt writers to
consider providing this sort of information. The fixed location of this element in the
task content model will promote consistency across tasks increasing findability for the
- It is another element that maintainers have to implement and document. Users will need
to learn the element’s intent.
- We intend to include a section in the Architectural Specification to explain how the new
troubleshooting elements should be used (when to use one versus the other). We will also
provide a description and examples for the DITA Language Specification.
The impact would be as follows
- Maintainers of the DTDs and XSDs would have to add the tasktroubleshooting specialization
- Editors of the DITA specification would have add “tasktroubleshooting” and its semantic
intent to the element reference.
- Vendors of tools: XML editors, component content management systems, and processors may add
auto-generated text support in their style-sheets to insert a “Troubleshooting” label.
- DITA community-at-large would perceive this change as a minor improvement in
<result>The <uicontrol>User Type</uicontrol> menu updates to display the new types you added.</result>
<tasktroubleshooting>If the User Type menu does not display the additions, manually refresh the page.</tasktroubleshooting>
This "Notes" section is not a required section per the proposal template, but the Subcommittee
would like to record some discussions that may be interesting as a reference in the future.
- The TC and SC considered allowing a more flexible element ordering in "taskbody", but the
guidance of the TechComm SC was that a rigid order was preferred.
- The TC and SC considered allowing the new <tasktroubleshooting> element any number of
times instead of an optional single occurrance. Both parties determined that this level of
flexibility would not be valuable. If flexibility is required for the sake of filtering, then
users should implement conditional filtering on elements within the tasktroubleshooting