Hi, Susan.
Thanks for making changes; this is getting closer. I'd suggest
further amending the proposal using the excellent suggestions that
Seth posted to the list on Wednesday; my changes are marked in red and
basically address just two points:
- The proposal needs to clearly state the proposed content model
in such a way that the maintainers of the DTDs and XSDs could
implement the changes.
- The proposal needs NOT to specify that an auto-generated task
label "Troubleshooting" must be applied by
implementations. This is an implementation choice and not
something that the DITA specification can mandate, especially as
it does not do so for any of the other key elements in
<task>. This clearly needs to be a best practice, of
course ...
Thanks again for your work.
Kris
________________________________
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
- 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.
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. The content model for
<tasktroubleshooting> would be:
( ( prereq)
(optional) then (
context)
(optional) then (
steps
or
steps-unordered)
(optional) then (
result)
(optional) then
(tasktroubleshooting)
(optional) (
example)
(optional) then (
postreq)
(optional) )
"
- The new element will be
specialized from "section" and will have the same
content model as <example> -- that is, all
<section> elements except for <title>.
- 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). Processors may apply a label to content
in this element to distinguish "Troubleshooting"
information from other content.
- 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 -- if they currently
support generating task labels --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>
On 6/28/2012 7:02 PM, Susan Blaisdell
wrote:
Submitter's message
Updated version of proposal to add new task troubleshooting
section based on feedback from 6/26 TC meeting. Seth sent an email
to the SC list on 6/27 that has contains the feedback and includes
some optional considerations.
-- Susan Blaisdell
--
Best,
Kris
Kristen James Eberlein
Principal consultant, Eberlein Consulting
Co-chair, OASIS DITA Technical Committee
Charter member, OASIS DITA Adoption Committee
www.eberleinconsulting.com
+1 919 682-2290; kriseberlein (skype)
|