[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]
Subject: RE: [dita-techcomm] Groups - Proposal 13096 to add a new troubleshooting section in a task topic (HTML) uploaded
Thanks, Kris. A few modifications in
blue. -sp From: dita-techcomm@lists.oasis-open.org [mailto:dita-techcomm@lists.oasis-open.org]
On Behalf Of Kristen James Eberlein Hi, Susan.
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:
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>. The new tasktroubleshooting element, like “result”,
will have the same content model as “section” except that “title” will not be permitted. 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:
The strict Task constraints domain must be edited to allow the new element. Element:
A new element “tasktroubleshooting” would have to be added.
The content model for <taskbody> would be:
The new element will be specialized from "section" and will have the same content model as <result> -- that is, all <section> elements except for <title>. Attributes Inherit same attribute definition as specialization base ("section"). Processing impact
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
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:
-- 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) |
[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]