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:
  • Third draft of proposal completed on 6/28
  • Champion of the proposal: DITA Technical Communications Subcommittee

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.

Proposed solution

Add a new element named <tasktroubleshooting> to task topics that could be added after <result> and before <example>. An auto-generated label of “Troubleshooting” should be applied.

The new tasktroubleshooting element will be specialized from "section" and will have the same content model except that there will be no title element <<Seth: Not sure I interpreted this correctly from your email>>.

Benefits

Technical requirements

Provide a detailed description of how the solution will work. Be sure to include the following details:
DTD and Schema modifications
Topic or map specialization
None
Domain
None
Element
A new element “tasktroubleshooting” would have to be added
Attributes
Inherit same attribute definition as specialization base ("section").
Processing impact
Style-sheets would have to add auto-generated text support for this element (e.g., “Troubleshooting” in English).
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.
Documentation
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.

Costs

The impact would be as follows
  • Maintainers of the DTDs and XSDs would have to add the tasktroubleshooting specialization to task. This could be quickly accomplished by cloning the result specialization and renaming it tasktroubleshooting.
  • 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, processsors, would need to 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 convenience.

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>