Substeps within steps

Task topics allow two levels of steps within a single procedure: steps and substeps. Where possible, substeps should be avoided.

In DITA, procedural steps can be structured in two levels: steps and substeps. Any step within a steps block can be broken down into substeps, but a substep cannot be further broken down.

If a procedural step is broken down into substeps, the substeps section can be used within an individual step (as a child of the cmd element). In other cases, a choicetable structure, designed for decision points in a step, may be appropriate.

The substeps element contains one or more substep elements, which are almost identical to the step element.

Avoid substeps whenever possible. If a step is a task in itself, it is best approach is to document that secondary task in a separate topic, and cross-reference the task topic to the second task topic. Your task should ideally be made up of a single level of steps. Re-writing a procedure is sometimes necessary to find a way of simplifying it to one level.

If you are documenting a procedure with two or more distinct variants, such as a procedure describing how to enable JavaScript in different browsers, you should create different task topics for each variant. For example, you would create one topic for Enabling JavaScript in Internet Explorer, another for Enabling JavaScript in Safari, and so on.

If the variation between procedures is only very slight, you may be able to write a single procedure but use choices or choicetable elements to distinguish the differences.