DITA 1.3 proposed feature 13096, troubleshooting section in task

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
  • Phase 2 Proposal

Original requirement

Add troubleshooting section with a task: There is often a need to include a troubleshooting section in a task, between the <result> and <postreq>. 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 before reading the <postreq> section, since their is no sense in moving forward if the expected result was not achieved.

Use cases

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 achieved.

Benefits

Costs

The impact would be as follows:

Technical requirements

Element
  • The proposed element name is “tasktroubleshooting”
  • The “tasktroubleshooting” element specializes “topic/section”
  • A new element “tasktroubleshooting” is to be added as an optional sibling in between <result> and <example> in the taskbody content model. The strict Task constraints must also be modified to allow tasktroubleshooting.
  • This element is a translatable container element
Attributes
The attributes are “outputclass” plus those contained within the “univ-atts” parameter entitiy (this is the same combination as those available with the result element)
Overall usability

This proposal would improve usability more than damage it.

Pro
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 reader.
Con
It is another element that maintainers have to implement and document. Users will need to learn the element’s intent.

Examples

<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>