DITA Generic Task Model

DITA 1.2 Specification

New Features with 1.2

Draft – JoAnn Hackos – November 3, 2008

DITA Generic Task Model

Use the DITA Generic Task Model to create a wide variety of procedural information.

Purpose of the change

The DITA Task Model is the most restrictive of the DITA information types. The DITA 1.1 task model requires that pre-requisites precede context in the <conbody>; that title is not permitted in pre-requisites, context, or post-requisite elements, that nothing come before the <cmd> in a step, and so on.

The new DITA Generic Task Model is less restrictive to support variations in the way that organizations create procedural information for their customers.

The new DITA Task Model allows authors to

Insert an admonition (warning, caution, etc.) before the user action statement <cmd>. In many style guides, admonitions must precede the step. In the DITA 1.1 task model, the admonition had to be inserted in the previous step.
Use ordinary numbered and bulleted lists (<ol> and <ul>) instead of the highly structured <step> elements through the use of <steps-informal>. This flexibility makes conversion from unstructured steps easier to accomplish. <draft-comment> I don’t see this as a good thing.</draft-comment>
Add a <stepsection> for information a user needs before the <steps> begin.
Create a section (with an optional title) before the steps in the task. Optional titles within a task accommodate many existing authoring guidelines.
Change the order of <prereq>, <context>, and <section> before the steps in the task. It's common for organizations to present <context> information before <prereq>, and, in the past, the DITA-OT stylesheets had to be customized to switch them around, which is beyond the capability of most users who are not well-versed in advanced XSLT coding techniques.s
Add expository text between <step> elements. More information can be added to the step without having that information embedded in the <step> element, allowing for easier reuse of a <step>.

In addition, DITA 1.2 includes the new Machine Industry task model, which supports many of the requirements found in S1000D[GLJ1]. We describe the Machine Industry task in another new features article.

Generic task information model

DITA 1.2 provides two task models: one is the existing task model from DITA 1.0 and 1.1. We generally label this task model as being more strictly constrained. The new, more generic task model provides a looser task model that allows more variations. Both task models are supported in DITA 1.2.

<codeblock>(prereq or context or section)*, (steps or steps-unordered or steps-informal)?, result?, example*, postreq*</codeblock>

The generic task model start with zero or more pre-requisite, context, or generic sections in any order, followed by an optional single occurrence of steps, unordered steps, or informal steps, followed by an optional single occurrence of result, followed by zero or more examples, followed by zero or more post-requirement sections.

Note that <example> and <postreq> are optional and repeatable while <result> is optional. <prereq>, <context>, and <section> are optional and repeatable and may occur in any order. <steps>, <steps-unordered>, and <step-informal> are each options that may be used for the procedural list in a task.

Steps-informal

The <steps-informal> element allows you to describe procedural task information that would not normally be ordered as steps, such as a group of generic procedures that may all be applied in a particular situation. A typical example might be a Troubleshooting procedure that identifies one symptom and then provides more than one procedure for correcting the problem. This element is also designed to be used for specialization of the structure of steps.

Instead of <steps>, you can use the <steps-informal> element with <ol> and <li> elements. Instead of <steps-unordered>, you can use the <steps-informal> element with <ul> and <li> elements. The <steps-informal> element can contain <ol> or and <li> elements, which are less strictly structured than <step> elements and therefore offer the following benefits:

The contents of an <ol> can often be copied directly from HTML and pasted into DITA; this is not the case for <steps> or <steps-unordered> elements.
The <ol> and <li> elements tend to be better supported by the “numbered list” features in XML authoring tools.
When converting legacy content, it will generally be easier to convert numbered lists to <ol> elements than to <steps> elements.

One drawback of <steps-informal> is that it cannot contain a <stepsection> element, as described below.

Step section

Within the <steps> or <steps-unordered> elements, you can add expository text using the new optional <stepsection> element.

<codeblock<stepsection?, step)+</codeblock>

As indicated in the DTD code, an optional stepsection may precede any step, allowing you to provide information that is not actually part of the step. Note that you will have to adjust your stylesheet to ensure that the <stepsection> is not numbered with the steps, if that is the behavior you prefer.

You can also add one or more optional notes or a hazard statement before the <cmd> element in a step, as shown in the syntax below.

If you include the Hazard Domain with your DITA model, you can insert the new <hazardstatement> before a command. Many DITA users have identified the need for warnings, cautions, or other hazards to precede steps but that are not part of the previous step. The new placement of notes and hazard statements helps to consolidate information around a step and simplifies the reuse of step content.

The new <itemgroup> element allows you to group several steps together in order to make reusing them simpler. //Robert is checking on this. We’re not certain how this is supposed to work//

Examples

Here are examples of the three options available for the new generic DITA task models.

Note to TC members: Please help to supply complete and realistic examples.

Regular ordered steps with added <section> element

<task>
<title>Lifting the pump assemblies</title>
<shortdescrip>Use this procedure to lift the PS ANSI combo pump units.</shortdescrip>

<taskbody>
<context>PS units may be mounted with equipment installed or with no equipment installed.</context>

<prereq>PS units are transported on wooden pallets via forklift truck to the area where they will be installed.<note othertype=”warning” type=”other”>Never transport a PS unit over a long distance or over rough terrain while it is suspended from slings.</note</prereq>
<section>
<title>Trained personnel</title>

<p>Ensure that lifting is handled only by trained personnel.</p>
</section>
<steps>
<stepsection>If you are lifting a unit with the motor installed, perform the first step, otherwise continue with the second step.</stepsection>

<step<cmd>Check to see that the pump suction nozzle does not interfere with the lifting sling. If it interferes, remove it before proceeding.</cmd</step>

<step<cmd>Remove the metal shipping straps that hold the PS unit to the wooden pallet.</cmd</step>

<step>

<note type=”warning”>Do not install eyebolts in the PS thread inserts to lift the base. This practice imposes lateral loads on the inserts that they are not designed to withstand.</note>

<cmd>Slip slings under each end of the PS unit as a harness.</cmd</step>

<step>
<note type=”danger”>Keep hands and feet out from under the PS unit during these steps. If slings slip and the unit tips over, severe personal injury or death may result, as well as irreparable damage to the PS unit.</note>

<cmd>Lift the PS unit a few inches off the pallet and verify that it hangs reasonably level and that the slings are not prone to slip out of position.</cmd</step>

<step<cmd>If the sling appears to be unstable, set the PS unit back on the pallet and reposition the slings.</cmd</step>

…
</taskbody</task>

Steps unordered

<task>

<title>Locating the pump</title>

<shortdescrip>Consider these issues when you decide where to locate the pump.</shortdescrip>

<section<title>Applicable units</title>

<p>Apply these standards to JM or JP units.</p</section>

<steps-unordered>

<step<cmd>Locate the pump as near your liquid source as practical.</cmd</step>

<step<cmd>Allow adequate space for servicing and ventilation.</cmd</step>

…

</steps-unordered</task>

Steps informal

<task>
<title>Lifting the pump assemblies</title>
<shortdescrip>Use this procedure to lift the PS ANSI combo pump units.</shortdescrip>

<taskbody>
<context>PS units may be mounted with equipment installed or with no equipment installed.</context>

<prereq<p>PS units are transported on wooden pallets via forklift truck to the area where they will be installed.<note othertype=”warning” type=”other”>Never transport a PS unit over a long distance or over rough terrain while it is suspended from slings.</note</p>

<p>Ensure that lifting is handled only by trained personnel.</p>
</prereq>

<steps-informal>

<p>If you are lifting a unit with the motor installed, perform the first step, otherwise continue with the second step.</p>

<ol<li>Check to see that the pump suction nozzle does not interfere with the lifting sling. If it interferes, remove it before proceeding.</li>

<li>Remove the metal shipping straps that hold the PS unit to the wooden pallet.</li>

<p<note type=”warning” Do not install eyebolts in the PS thread inserts to lift the base. This practice imposes lateral loads on the inserts that they are not designed to withstand.</note</p>

<li>Slip slings under each end of the PS unit as a harness.</li>

<p<note type=”danger”>Keep hands and feet out from under the PS unit during these steps. If slings slip and the unit tips over, severe personal injury or death may result, as well as irreparable damage to the PS unit.</note</p>

<li>Lift the PS unit a few inches off the pallet and verify that it hangs reasonably level and that the slings are not prone to slip out of position.</li>

<li>If the sling appears to be unstable, set the PS unit back on the pallet and reposition the slings.</li</ol>

…
</taskbody</task>

[GLJ1]Is this the correct standard? I thought S1000D dealt with dynamic delivery of content, and deeper architecture of the content (I may be wrong here, but I thought the MI were trying to be in sync with a different standard).