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
- 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 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.
Add a new element named
<steptroubleshooting> to task topics that could be added after
<stepresult> within a step element.
- This addition will benefit writers who want to provide important
troubleshooting information within a step right at the point
of need by the users. The troubleshooting element becomes an
explicit reminder to the writer that troubleshooting advice should
be considered, in contrast to requiring that they add <info>
and then create a troubleshooting note.
- This enhancement will have a significant impact because key troubleshooting
information will be called out and not be missed by users.
- DTD and Schema modifications
- Topic or map specialization
- 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”.
- 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.
- 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.
- Adding another element makes the DTD larger. However, the constraint
mechanism could easily remove the optional steptroubleshooting element
from the step element content model.
- 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 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
- DITA community-at-large would perceive this change as a minor
improvement in convenience
<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>