Structuring DITA Concept Topics

Structuring content within a DITA concept topic involves organizing information in a logical and coherent manner to effectively convey the concept to your audience. Since a DITA concept topic is used to explain a specific idea or concept, these rules and guidelines will ensure that your content is properly structured for that purpose:

Title

Begin with a clear and descriptive title that captures the concept you are explaining.

Introduction

Provide a brief introduction that sets the context for the concept. This should explain why the concept is important and what the reader will gain from understanding it.

Main Content

The main body of the concept topic should elaborate on the concept in a structured manner. Use a combination of DITA elements to organize your content:

Definition

It is generally good to start with a clear definition or explanation of the concept. Use the <p> (paragraph) element for this purpose.

Examples

Providing relevant examples or scenarios that illustrate the concept greatly improves reader understanding. Use <example> elements or <p> elements for this.

Related Terminology

If there are specific terms or jargon associated with the concept, you should include a section or list (using <glosslist>, <glossentry>, and <glossterm>) that defines and explains these terms.

Key Points

Summarize the key points or characteristics of the concept using lists, such as <ul> (unordered list) or <ol> (ordered list), for easy readability. Ensure that the list supplements the preceding paragraph(s), and does not introduce new information.

Diagrams and Visuals

Use <fig> and <image> elements to include diagrams, charts, or visuals that help explain the concept visually.

Cross-References

If the concept is related to other topics, you can include cross-references (using <xref>) to those topics for further reading.

Conclusion

Summarize the key takeaways and reiterate the significance of the concept. This may not be required depending on the length of the concept topic, but a long explanation should have a concluding summary.

Related Topics

Optionally, include a section at the end that lists related topics or concepts that the reader might want to explore next. Use <related-links> or <related-topic> elements for this purpose.

References

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

Additional Information

Any supplementary information, notes, or warnings related to the concept can be included in an “Additional Information” section.