DITA 1.2: Task Model Feature Article
DITA 1.2 introduces the General Task Model as an alternative to the DITA 1.0 and 1.1
Strict Task Model. It also adds capabilities to the <steps> content unit for both task
models.
Use the DITA General Task Model when your information model calls for a task structure
that is not well supported by the DITA Strict Task Model or when you need to constrain
the elements in a task in a way that is unique to your organization’s needs. Use the
DITA General Task Model to convert existing tasks to DITA that do not yet conform to
your task information model.
DITA 1.2 also includes the new Machinery Task Model, designed to conform to the
requirements of the machine industry, especially in the construction of pre- and
post-requirements. The Machinery Task Model is described in Please insert a link to the Machinery task model feature article to
the OASIS page.another features article.
Purpose of the General Task Model
The DITA Strict Task Model is the most restrictive of the DITA information types. For
example, the DITA Strict Task Model, originally introduced in DITA 1.0 and
maintained in DITA 1.1 and 1.2, requires that pre-requisites precede context in the
<conbody> and does not permit titles for pre-requisites, context, result, or
post-requisite content units.
The new DITA General Task Model, introduced with DITA 1.2, is less restrictive to
support variations in the way that organizations create procedural information. The
General Task Model can be the basis for specific constraints required by the
organization or it can be used to support a more opened way of developing task
information.
The new DITA General Task Model allows the following:
- Delete the text "Add "Add a
<section> with an optional <title> before the steps in the task.
- Vary the order of <prereq>, <context>, and <section> before the steps
in the task. It's common for some organizations to present <context>
information before <prereq>, and, in the past, the DITA-OT Why mention DITA-OT in this context? It's got nothing to do
with the DITA-OT per say -- whatever tool a user uses to publish their DITA
content, that tool needs to be heavily customized to switch the order of
elements in the rendered output -- regardless of tool. Please delete the
word "DITA-OT" since it's not relevant in this
context.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.
- Replace "Select the " with "A
"Select the new <steps-informal> content unit, which allows
you to construct steps using ordered and unordered lists, paragraphs, and other
less semantically specified elements than <step> and <cmd>.
- Delete the text "Include
"Include more than one example or pre-requisite in a task after
the completion of the steps.
Precautions in mixing task modelsNote that the DITA General Task
Model, the DITA Strict Task Model, and the Machinery Task Model are not mutually
compatible. Both DITA Strict Task Model and the Machinery Task Model have been
redesigned as constraints of the General Task Model.You are not able to use a conref
between a constrained and a more general task model. A constrained task cannot
conref from an unconstrained task. Conref requires that the conref target be at
least as constrained (and compatibly constrained) as the conref source (that is, the
document making the conref link). Otherwise, you cannot be assured that the conrefed
data is valid in the using context.
We advise organizations to use only one
task model unless the content in two areas of publications is completely mutually
exclusive and will never be shared. Note, however, that a fundamental DITA principle
is the ability to exchange content throughout an organization. It is, therefore,
best to avoid using more than one task model.
Steps-informalThe <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.The
<steps-informal> element can contain <ol> or <ul> 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.
- When converting legacy content, it may 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.
Steps and steps-unordered
Both the General Task Model and the Strict Task Model incorporate new elements into
the <steps> and <steps-unordered) content units.
Within the <steps> or <steps-unordered> elements, you can add expository text
using the new optional <stepsection> element. The optional <stepsection> may
precede any <step>, allowing you to provide information that is not actually part
of a step. Note that you Typo. Replace "way" with
"may".way 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 hazard statements before the <cmd>
element in a step.
If you include the Hazard Domain with your DITA shell 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 should not be written as a
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.
General Task Model example
In this example using the General Task Model, the <context> element precedes the
<prereq> element. In addition, a <section> is added with a <title> before
the steps begin. The <steps> contain a <stepsection> before the <step> list
begins. A warning and a danger occur within <note> elements before the <cmd>
of the step.
Note that additions to the <steps> appears in both the General Task Model
and the Strict Task Model.
<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 example
This example change "include" to
"includes"include a <section> with a <title> prior to the
beginning of the <steps-unordered> content unit.
<task>
<title>Locating the pump</title>
<shortdescrip>Consider these issues when you decide where to
locate the pump.</shortdescrip>
<taskbody>
<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>
</taskbody>
</task>
Steps-informal exampleIn the next example, the <context>
content unit precedes the <prereq> content unit. <steps-informal> allows
paragraphs, ordered lists, unordered lists, and other body
elements.
<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></ol>
<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>
<ol><li>Slip slings under each end of the PS unit as a harness.</li></ol>
<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>
<ol><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>
<steps-informal>
allows authors to use basic HTML for ordered lists, greatly simplifying the DITA
markup in comparison with the more semantically rigorous <steps>.
Another
possible application of <steps-informal> allows an author to address a very different
model of procedural information. A good example is the classic recipe style in which a
number of actions are combined in a single numbered
step.Here’s a typical recipe structure.
<task><title>Argula parmesan salad</title>
<shortdesc>The vegetable Arugula has a distinctive appealingly
peppery flavor. Use just a touch of sweet balsamic vinegar to
enhance rather than mask it.</shortdesc>
<taskbody>
<prereq><sl><li>1 tbsp. plus 2 tsp. red-wine vinegar</li>
<li>1 tsp balsamic vinegar</li>
...</sl>
</prereq>
<context><p>Serves 8 Time 15 minutes </p></context>
<draft-comment>It would be nice to specialize these data
items.</draft-comment>
<steps-informal>
<ol>
<li>In a bowl, whisk together vinegars, garlic, and olive oil.
Add salt and pepper to taste.</li>
<li>Put arugula in a large bowl and toss with herbs and dressing.
</steps-informal>
</taskbody>
</task>
Note
that this recipe is quite short. Sometimes a single step in a recipte will have
10-15 actions. This example of <steps-informal> would allow authors to indicate a
set of steps, perhaps enabling a specialization of the <ol> to <recipe-steps>.
It would allow a different structure than the strict task Change "mode's" to "model's"mode's sequence of
<cmd> and <info>, better accommodating the multiple actions typically
described in a recipe “step.”