Home
Language reference: All-inclusive edition
The language reference portion of the DITA specification contains a topic for each DITA element. The topic defines the element, its inheritance hierarchy, and provides examples of usage. This portion of the DITA specification also includes information about DITA attributes.
Technical content elements
Elements in the technical content section include the original Concept, Task, and Reference specializations, as well as specializations added in later releases. It also includes domains designed primarily for technical content.
Task elements
Task topics answer "How do I?" questions, and have a well-defined structure that describes how to complete a procedure to accomplish a specific goal. Use the task topic to describe the steps of a particular task, or to provide an overview of a higher-level task. The task topic includes sections for describing the context, prerequisites, actual steps, expected results, example, and expected next steps for a task. For more details on when to use task and other information types, please refer to the DITA architectural specification.
<steptroubleshooting>
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.

Specification URIs
Notices
Introduction to DITA 1.3
The Darwin Information Typing Architecture (DITA) specification defines a set of document types for authoring and organizing topic-oriented information, as well as a set of mechanisms for combining, extending, and constraining document types.
Architectural specification: All-inclusive edition
The architectural specification portion of the DITA specification outlines the framework of DITA. It contains an overview of DITA markup; addressing; processing; configuration, specialization, generalization, and constraints; as well as information about coding DITA grammar files.
Language reference: All-inclusive edition
The language reference portion of the DITA specification contains a topic for each DITA element. The topic defines the element, its inheritance hierarchy, and provides examples of usage. This portion of the DITA specification also includes information about DITA attributes.
- Element quick reference
  This section contains a listing of DITA elements.
- Topic elements
  The base topic elements include elements that make up the core building blocks of the DITA topic, such as topic, body, and related-links, as well as elements like <p> and <ph> that are used in many topic specializations. Some of these elements are also available inside the <topicmeta> map element.
- Map elements
  Map elements include the core components of DITA maps, such as <topicref> and <reltable>, as well as general purpose map specializations in the map group domain.
- Metadata elements
  Metadata elements include information that is located within the <topicmeta> element (in maps) or <prolog> element (in topics), as well as indexing elements that can be placed in additional locations within topic content.
- Domain elements
  General purpose domains are not specific to any type of information, such as the hazard statement domain that provides elements for describing hazardous situations.
- Classification elements
  Classification elements support managing metadata. Those in the subject scheme map are used to define controlled values and to bind the controlled values to DITA attributes as enumerations. Those declared in the classification domain are used in other maps to classify content according to the scheme.
- Specialization elements
  Several DITA elements exist either for architectural reasons or for support of specialized markup yet to be designed. Although there is little need to use these elements unless you are directed to, some of them, such as <state>, can be used if your content makes use of these semantic distinctions. For example, a discussion of signals on a gate of an integrated logic circuit might use the <state> element to represent either on or off conditions of that gate.
- Legacy conversion elements
  Conversion elements exist primarily to aid in the conversion of content to DITA.
- DITAVAL elements
  A conditional processing profile (DITAVAL file) is used to identify which values are to be used for conditional processing during a particular output, build, or some other purpose. The profile should have an extension of .ditaval.
- Technical content elements
  Elements in the technical content section include the original Concept, Task, and Reference specializations, as well as specializations added in later releases. It also includes domains designed primarily for technical content.
  - Concept elements
    DITA concept topics answer "What is..." questions. Use the concept topic to introduce the background or overview information for tasks or reference topics. The concept topic restricts content following a section or example to other sections or examples. For more details on when to use concept and other information types, please refer to the DITA architectural specification.
  - Task elements
    Task topics answer "How do I?" questions, and have a well-defined structure that describes how to complete a procedure to accomplish a specific goal. Use the task topic to describe the steps of a particular task, or to provide an overview of a higher-level task. The task topic includes sections for describing the context, prerequisites, actual steps, expected results, example, and expected next steps for a task. For more details on when to use task and other information types, please refer to the DITA architectural specification.
    - <task>
      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.
    - <taskbody>
      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.
    - <prereq>
      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.
    - <context>
      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.
    - <steps>
      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.
    - <steps-informal>
      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.
    - <steps-unordered>
      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.
    - <step>
      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.
    - <stepsection>
      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.
    - <cmd>
      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>.
    - <info>
      The <info> element occurs inside a <step> element to provide additional information about the step.
    - <substeps>
      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.
    - <substep>
      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.
    - <stepxmp>
      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.
    - <choicetable>
      The <choicetable> element contains a series of optional choices available within a step of a task.
    - <chhead>
      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.
    - <choptionhd>
      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.
    - <chdeschd>
      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.
    - <chrow>
      The <chrow> element is a container inside the <choicetable> element. The <chrow> element contains both a <choption> and <chdesc> element as a pair.
    - <choption>
      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.
    - <chdesc>
      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.
    - <choices>
      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.
    - <choice>
      Each <choice> element describes one way that the user could perform the current step.
    - <steptroubleshooting>
      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.
    - <stepresult>
      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.
    - <tutorialinfo>
      The <tutorialinfo> element contains additional information that is useful when the task is part of a tutorial.
    - <tasktroubleshooting>
      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.
    - <result>
      The <result> element describes the expected outcome for the task as a whole.
    - <postreq>
      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.
  - Reference elements
    Reference topics describe factual material about a subject, such as the commands in a programming language. This format is also suitable for bibliographies, catalogues, the list of ingredients for recipes, and similar collections of structured descriptive prose. For more details on when to use reference and other information types, please refer to the DITA architectural specification.
  - Troubleshooting elements
    Troubleshooting topics document corrective action such as troubleshooting or alarm clearing.
  - Glossary elements
    Glossary elements include those elements designed to specify terms and their definitions, as well as elements that are designed to group, reference, or otherwise make use of information in the glossentry topic.
  - Bookmap elements
    Elements in the bookmap section are used to organize DITA content into book form. They include elements for dividing up content, such as chapter and appendix, as well as metadata specific to publishing.
  - Technical-content domains elements
    Domains in this section include those generally associated with technical content, such as the programming and software domains.
- Learning and training elements
  Elements in the learning and training section include specialized topics, maps, content, and metadata elements specially designed to support instructional content.
- Attributes
  This section collects commonly used attributes, with common definitions. If an element uses a different definition, or narrows the scope of, an otherwise common attribute, it will be called out in the topic that defines the element.
Conformance
Conformance to the DITA specification allows documents and document types that are used with different processors or different versions of a processor to produce the same or similar results with little or no reimplementation or modification.
Acknowledgments
(Non-normative) Many members of the OASIS DITA Technical Committee participated in the creation of this specification and are gratefully acknowledged.
Non-normative information
This section contains non-normative information, including topics about new features in DITA 1.3 and migrating from DITA 1.2 to DITA 1.3.
Content models for learning and training package
For each element in the learning and training package, this section presents the content model and a list of parent elements that can contain that element.

`<steptroubleshooting>`

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.

Tip: Do not use <note type="trouble"> inside of <steptroubleshooting> because its meaning there would be ambiguous.

Content models

See appendix for information about this element in OASIS document type shells.

Inheritance

- topic/itemgroup task/steptroubleshooting

Example

The following example illustrates using the <steptroubleshooting> element with a single action:

  <step>
    <cmd>Select <uicontrol>Perform system backup</uicontrol></cmd>
    <stepresult>
      <p>The message <systemoutput>Backup successfully
        completed</systemoutput> displays.</p>
    </stepresult>
    <steptroubleshooting>
      <p>If an error message displays during the system backup,
        locate the error ID in the <cite>Troubleshooting Guide
        </cite> and follow the instructions there.</p>
    </steptroubleshooting>
  </step>

The following example illustrates using the <steptroubleshooting> element with several actions:

  <step>
    <cmd>Log in to the system</cmd>
    <stepresult>
      <p>The <wintitle>Welcome</wintitle> screen appears.</p>
    </stepresult>
    <steptroubleshooting>
      <p>If the <wintitle>Welcome</wintitle> screen does not
        appear, try one or more of the following:
        <ul>
          <li>Verify that the user name was entered correctly</li>
          <li>Verify that the password was entered correctly</li>
          <li>Confirm that the maintenance contract is still
            active</li>
        </ul>
      </p>
    </steptroubleshooting>
  </step>

Attributes

The following attributes are available on this element: Universal attribute group and outputclass.