Hi Kris,
General task was largely done by a TC member who is no longer active. Can’t recall his name. We had a lot of problems describing the General Task in the DITA
1.2 specification because there was almost no information provided about its content model.
JoAnn
JoAnn T. Hackos, PhD
President
Comtech Services Inc.
710 Kipling Street, Suite 400
Denver, CO 80215
joann.hackos@comtech-serv.com
skype joannhackos
From: dita-techcomm@lists.oasis-open.org [mailto:dita-techcomm@lists.oasis-open.org]
On Behalf Of Kristen James Eberlein
Sent: Friday, June 29, 2012 2:26 PM
To: dita-techcomm@lists.oasis-open.org
Subject: Re: [dita-techcomm] Groups - Proposal 13096 to add a new troubleshooting section in a task topic (HTML) uploaded
Thanks, Seth -- I'm glad that you caught my error in specifying <task> rather than <taskbody>.
Are there any members of this subcommittee who were active with the TC when the content model for the general task was created?
I'm looking at the content model:
<!-- LONG NAME: Task Body -->
<!ENTITY % taskbody.content
"(((%prereq;) |
(%context;) |
(%section;))*,
((%steps; |
%steps-unordered; |
%steps-informal;))?,
(%result;)?,
(%example;)*,
(%postreq;)*)"
Kind of surprised to see that multiple examples and postreqs are permitted since only one result is allowed.
If folks need a reminder on how to read the syntax:
| indicates a choice between elements, for example, either <steps> or <steps-unordered> or <steps-informal>
* indicates that an element can occur zero or multiple times, for example, <example> or <postreq>
? indicates that an element can occur zero or one times, for example, whatever step element is chosen
Kris
On 6/29/2012 3:54 PM, Park Seth-R01164 wrote:
Thanks, Kris.
A few modifications in
blue.
-sp
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, like “result”,
will have the same content model as “section” except that “title” will not be permitted.
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:
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:
( (
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 <result> -- 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)
--
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)