Home
Syntax and mark-up
Procedures and steps
The purpose of procedural documents is to explain to the reader how to accomplish tasks. The task information type is specifically designed for procedures, with a well-defined structure built around steps.
Semantics in steps
The steps of a procedure are defined in a task topic. Task topics typically have a simple structure of a single set of steps, but some procedures may require a more sophisticated structure that includes substeps and decision points.

Introduction
Information types and topics
Topics are the building blocks of modular documents, and organising topics by semantic information types is one of the architectural features of DITA.
DITA map files
Syntax and mark-up
- Organisation of DITA elements
  Elements in DITA are grouped together into a number of categories for organisational and comprehension purposes.
- Working with mark-up
- Element domains
  Elements in DITA are arranged into domains for organisational purposes and technical reasons.
- Short descriptions
  The short description (or shortdesc) is arguably the most important component of a DITA topic, and is also one of the most difficult elements to write. Short descriptions should be written for every topic.
- Lists
  The purpose of a list is to make it easier for the reader to understand sequences of information and collections of like information. Different types of lists are used for different information structures.
- Paragraphs
  Paragraphs are the basic components of topics. A paragraph (p) element should be a self-contained unit dealing with one idea or point, typically expressed in two or more related sentences. The p element should be used when no other semantically-specific block element is available.
- Procedures and steps
  The purpose of procedural documents is to explain to the reader how to accomplish tasks. The task information type is specifically designed for procedures, with a well-defined structure built around steps.
  - Semantics in steps
    The steps of a procedure are defined in a task topic. Task topics typically have a simple structure of a single set of steps, but some procedures may require a more sophisticated structure that includes substeps and decision points.
  - Separating procedures into granular steps
    Steps within a task topic must be written so that a single step contains just one user action (known in DITA as a command).
  - Restricting tasks to one procedure only
    Task topics can only contain one procedure, with one continuous set of numbered steps.
  - The prereq element
    The pre-requisites (prereq) element describes the status or situation that must be established before a procedural task can be started. It can contain cross-references to pre-requisite task topics.
  - Substeps within steps
    Task topics allow two levels of steps within a single procedure: steps and substeps. Where possible, substeps should be avoided.
  - Single step procedure
    A procedure or task containing just one action should be marked-up using the normal steps/step/cmd structure.
  - The command element
    The command (cmd) element within the step element contains a single, active voice instruction to the reader.
  - Required and optional steps
    The importance attribute of a step is used to indicate whether an element is optional or mandatory.
  - Complex nested tasks
    A complex process made up of a number of procedures can be documented by collecting, through the ditamap, the constituent task topics under a process stub topic.
  - Notes and extra information in a step
    Information that supplements or supports a procedural step can be included within an info element. The info element in turn can contain block elements such as note elements.
  - Images within steps
    Images that support a procedural step can be included within a stepxmp or an info element.
  - Choice tables
    A choice table is used within a step in a task topic to describe a series of optional choices that a user must make before proceeding.
  - Non-sequential procedural steps
    Some procedures are not made up of sequential procedural steps. When documenting these procedures, the steps-informal structure or the steps-unordered structure should be used.
- Tables
  The purpose of a table is to structure, organise and present factual data that a user will need to look up or reference. There are two general purpose table types in DITA: table and simpletable.
- Phrases
  The semantics of words and phrases in DITA content is expressed through a broad range of phrase elements.
- Special characters and dates
Language and punctuation
Graphics and figures
Cross-referencing
Cross-references are a means of binding individual topics into a coherent and navigable document.
Content re-use
Metadata, conditional processing, and indexing
The DITA documentation process
DITA authoring concepts
Moving from style-based authoring to a structured authoring methodology such as DITA requires a radically different approach to writing.

Semantics in steps

The steps of a procedure are defined in a task topic. Task topics typically have a simple structure of a single set of steps, but some procedures may require a more sophisticated structure that includes substeps and decision points.

Of the three original base information types in DITA, the task type is the most strongly typed. In other words, the task information type has the strictest rules. A task must be made up of one set of steps only. If you feel you need more than one set of steps, you almost certainly need to create more than one task topic.

In most cases, a set of steps is made up of one or more step elements, with each step element comprising a mandatory command (cmd) element, and an optional stepresult element.

The syntax of a typical set of steps is as in the following example:

<steps>
  <step>
    <cmd>Turn the key to the right.<cmd>
    <stepresult>The engine light will illuminate.</stepresult>
  </step>
  <step>
    <cmd>Press the <uicontrol>Start</uicontrol> button.</cmd>
  </step>
</steps>

In some cases, the complexity of a set of steps requires a more complex structure. Three more sophisticated elements can be used in such cases:

substeps
choices
choicetable

Examples are often a good way of explaining a task, and the task information type allows one (optional) example of a step to be included (stepxmp) after any cmd element, and for one (optional) overall example to be included after the steps block.

Explanatory information to support a command can optionally be added after the cmd within a step through the info element.

Before the steps block, the context in which a task is performed can be described through a context element. If there are any pre-requisites or pre-conditions for a task to be performed, these can be described in the prereq element above the steps block.

After the steps block, any post-requisites can be described (using the postreq element), and the overall result of the task steps can be described in a result element.

The overall structure of a task topic is:

<task>
 <shortdesc>...</shortdesc>
 <taskbody>
  <prereq>...</prereq>
  <context>...</context>
  <steps>
  ...
  </steps>
  <result>...</result>
  <example>...</example>
  <postreq>...</postreq>
 </taskbody>
</task>