DITA 1.3 proposed feature 13096
Proposal to add a new element to support a troubleshooting
section between the <result> and <postreq> elements in a task
Date and version information
- Second draft of proposal completed on 6/20
- 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 <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.
Add a new element named
<tasktroubleshooting> to task topics that could be added after
<result> and before <postreq>. An auto-generated label of “Troubleshooting”
should be applied.
- 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 information.
- 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
- DTD and Schema modifications
- Topic or map specialization
- A new element “tasktroubleshooting” would have to be added
- 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.
- 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.
- 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 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.
<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>