Structuring DITA Task Topics

Structuring content within a DITA task topic involves organizing instructions and steps in a clear and logical sequence to guide users through a specific task or procedure. Since a DITA task topic is used to provide how-to guides and procedural information, these rules and guidelines will ensure that your content is properly structured for that purpose:

Title

Start with a clear and descriptive title that summarizes the task or procedure.

Introduction (Optional)

Provide a brief introduction to set the context for the task. Explain why the task is necessary and any prerequisites that users should be aware of.

Task Body

The main body of the task topic should contain the step-by-step instructions for completing the task. Use a combination of DITA elements to structure the task content:

Steps

List the individual steps required to complete the task. Each step should be numbered or labeled and presented in a clear and sequential order. Use the <steps> element to group the steps, and within it, use <step> elements for each individual step.

Substeps

If a step contains sub-steps or sub-actions, you can use the <substeps> and <substep> elements to maintain the hierarchy. This is particularly useful for complex tasks.

Images and Graphics

Incorporate images, screenshots, diagrams, or other visuals to illustrate each step when necessary. Use <fig> and <image> elements to include these visuals.

Warnings and Notes

If there are important warnings, tips, or notes that users need to be aware of at specific steps, include them using <note> elements with appropriate attribute values like “caution,” “tip,” or “important.” Ensure that these elements have been placed correctly relative to the content.

Optional Steps (if applicable)

If the task includes optional steps or alternative approaches, clearly delineate them within the task content.

Conclusion (Optional)

Provide a result statement once all steps are completed.

Related Topics

Include a section at the end that lists related topics or tasks that users might find helpful for further information or related procedures. Use <related-links> or <related-topic> elements for this purpose.

References

If you’ve used external sources or references in your task instructions, include a section with citations or links to those sources.

Additional Information

Any supplementary information, troubleshooting steps, or frequently asked questions related to the task can be included in an “Additional Information” section.