Task elements

The <task> element is the top-level element for a task topic. Tasks are the main building blocks for task-oriented user assistance. They generally provide step-by-step instructions that will enable a user to perform a task. A task answers the question of "how to?" by telling the user precisely what to do and the order in which to do it. Tasks have the same high-level structure as other topics, with a title, short description and body.

The <taskbody> element is the main body-level element inside a task topic. A task body is designed to contain information specific to completing a task, such as prerequisites, contextual information, and steps. DITA 1.2 introduced a much looser <taskbody> content model in order to allow for more variations in the structure of a task. A constraint module was also provided in order to maintain compatibility with the previous strict model; this constraint is used in the default task distributed by OASIS.

The <prereq> element of a task contains prerequisites that the user needs to know or do before starting the current task. Implementations MAY render prerequisite links from the related-links section together with the <prereq> content.

The <context> element provides background information for a task. This information helps the user understand what the purpose of the task is and what they will gain by completing the task. This section should be brief and does not replace or recreate a concept topic on the same subject, although the context section might include some conceptual information.

The <steps> element provides the main content of a task topic. The task is described as a series of steps that the user must follow to accomplish the task. At least one <step> element is required inside the <steps> element.

The <steps-informal> element allows authors to describe procedural task information without placing each step in an individual container element, which is a requirement of the related <steps> and <steps-unordered> elements. For example, <steps-informal> might contain a paragraph that describes more than one step in a single sentence, or it might contain sentences that mix steps together with information about the steps.

Like the <steps> element, the <steps-unordered> element provides the main content of a task topic, but particularly for cases in which the order of steps might vary from one situation to another. At least one <step> element is required inside the <steps-unordered> element.

The <step> element represents an action that a user must follow to accomplish a task. Each step in a task must contain a command <cmd> element which describes the particular action the user must do to accomplish the overall task. Beginning with DITA 1.2, it is possible to place a <note> element before the command in order to notify the user of dangers or other important information about the step. The <step> element can also contain additional optional information about the step, such as sub-steps, a list of choices, or result information.

The <stepsection> element provides expository text before a <step> element. Although the element is specialized from <li> and has the same content model as a list item, it is not intended to represent a step in a task.

The <cmd> element specifies a command, which is a required element inside the <step> element. It provides the active voice instruction to the user for completing the step, and should not be more than one sentence. If the step needs additional explanation, place the explanation in an <info> element following the <cmd>.

The <info> element occurs inside a <step> element to provide additional information about the step.

The <substeps> element allows you to break a step down into a series of separate actions, and should be used only if necessary. Try to describe the steps of a task in a single level of steps. If you need to use more than one level of <substep> nesting, you should probably rewrite the task to simplify it.

A <substep> element has the same structure as a <step>, except that it does not allow lists of choices or sub-steps within it, in order to prevent unlimited nesting of steps.

The <stepxmp> element is used to illustrate a step of a task. The step example can be a couple of words, or an entire paragraph.

The <choicetable> element contains a series of optional choices available within a step of a task.

The <chhead> element is a container inside the <choicetable> element that provides specific heading text to override any default headings for the <choicetable> (such as "Option" and "Description"). The <chhead> element contains both a <choptionhd> and <chdeschd> element as a pair.

The <choptionhd> element provides a specific label for the list of options from which a user chooses in order to accomplish a step. The default label for the list of options could be a localized translation of Option.

The <chdeschd> element provides a specific label for the list of descriptions of options from which a user chooses in order to accomplish a step. The default label for the list of options could be a localized translation of Description.

The <chrow> element is a container inside the <choicetable> element. The <chrow> element contains both a <choption> and <chdesc> element as a pair.

The <choption> element describes an option in a choice table that a user could choose to accomplish a step of a task. In a user interface, for example, this might be the name of radio button.

The <chdesc> element is a description of an option from a choice table that a user chooses while performing a step to accomplish a task. It explains why the user would choose that option and might explain the result of the choice when it is not immediately obvious.

The <choices> element contains a list of <choice> elements. It is used when the user will need to choose one of several actions while performing the steps of a task.

Each <choice> element describes one way that the user could perform the current step.

The <steptroubleshooting> element provides information that is designed to help remedy the situation when a step does not complete as expected. In particular, this element can be used to explain how users can recover when the results of a step do not match those listed in the <stepresult> element.

The <stepresult> element provides information on the expected outcome of a step. If a user interface is being documented, the outcome could describe a dialog box opening or the appearance of a progress indicator. Step results are useful to assure a user that they are on track, but should not be used for every step as this quickly becomes tedious.

The <tutorialinfo> element contains additional information that is useful when the task is part of a tutorial.

The <tasktroubleshooting> element provides information designed to help users remedy the situation when a task does not complete as expected. In particular, this element can be used to explain how users can recover when the results of a task do not match those listed in the <result> element. The troubleshooting remedy typically contains one or more actions for solving a problem. For complex remedies, link to another task.

The <result> element describes the expected outcome for the task as a whole.

The <postreq> element describes steps or tasks that the user should do after the successful completion of the current task. It is often supported by links to the next task or tasks in the <related-links> section.