DITA 1.3 proposed feature 13086

Proposal to add a new element to support a troubleshooting statement after the <stepresult> element in a task topic.

Date and version information

Include the following information:
  • Second draft of proposal completed on 6/20
  • Champion of the proposal: DITA Technical Communications Subcommittee

Use cases

There is often a need to include a troubleshooting statement in a task step, following the <stepresult>. The purpose of this "trouble" statement is to help the reader resolve any problems that may arise should their step result not match the result stated in the <stepresult> section of the step. This use case helps the reader resolve a problem encountered while performing a specific step.

Proposed solution

Add a new element named <steptroubleshooting> to task topics that could be added after <stepresult> within a step element.

Benefits

Technical requirements

DTD and Schema modifications
Topic or map specialization
None
Domain
None
Element
A new element “steptroubleshooting” would have to be added as the optional last-child of the step element. The steptroubleshooting element would specialize “topic/note”. The type attribute on the steptroubleshooting element will be specified FIXED “trouble”.
Attributes
Same as the ones used for the note element. It makes sense to remove the othertype attribute because the type attribute will be FIXED. This means that the value “other” will not be allowed for type. Consequently, othertype could never be correctly used in this specialization.
Processing impact
None. Processing would fall back to that defined for “topic/note”.
Overall usability

This proposal would improve usability more than damage it.

Pro
The presence of the steptroubleshooting element would prompt writers to consider including alternatives for unexpected step results. The steptroubleshooting element’s position as optional last child of step would promote consistency with placement of that sort of information, reducing arbitrary differences in structure among steps.
Con
Adding another element makes the DTD larger. However, the constraint mechanism could easily remove the optional steptroubleshooting element from the step element content model.
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 steptroubleshooting specialization to task. This could be quickly accomplished by cloning the stepresult specialization and renaming it steptroubleshooting.
  • Editors of the DITA specification would have add “steptroubleshooting” and its semantic intent to the element reference.
  • Vendors of tools: XML editors, component content management systems, processsors, would not be significantly affected. Fallback processing for itemgroup should adequately accommodate the steptroubleshooting element.
  • DITA community-at-large would perceive this change as a minor improvement in convenience

Examples

<stepresult>The message "Backup successfully completed" displays.</stepresult>
<steptroubleshooting>If an eror message displays during the system backup, locate the error ID in the <cite>Troubleshooting Guide</cite>.</steptroubleshooting>