Structuring DITA Reference Topics

Structuring content within a DITA reference topic involves organizing information in a way that provides users with detailed and easily accessible reference material for specific elements, attributes, or components within your documentation. Since DITA reference topics are used to present and consolidate specific 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 reference topic, such as the name of the element, attribute, or component being documented.

Introduction (Optional)

Provide a brief introduction to set the context for the reference topic. Explain the purpose of the element, attribute, or component, and why users might need to refer to it.

Reference Information

a. Description

Begin with a comprehensive description of the element, attribute, or component. Use the <p> (paragraph) element for this purpose. Provide clear and concise information about its purpose, usage, and significance.

b. Syntax

If applicable, describe the syntax or format for using the element or attribute. Use the <codeblock> or <pre> elements for presenting code examples or syntax rules. These elements are specifically intended for this purpose.

c. Attributes (if element documentation)

If documenting an element, provide a list of its attributes, along with detailed explanations of each attribute’s purpose, values, and usage. The <table> or <dl> (definition list) elements are good options for this purpose.

d. Usage Examples

Include real-world examples that demonstrate how to use the element, attribute, or component in context. Use <example> elements or structured <section> elements for this.

e. Related Elements/Attributes

If relevant, mention related elements, attributes, or components that users might want to reference in conjunction with the current one. Use <related-links> or <related-topic> elements for this purpose.

f. Notes and Warnings

Include any important notes, warnings, or tips related to the element or attribute. Use <note> elements with appropriate attribute values like “caution,” “tip,” or “important.”

Default Values

If applicable, provide information about default values for attributes or elements.

Parent Elements

If documenting an attribute, list the elements to which the attribute can be applied. Use a <section> element for this purpose.

Child Elements

If documenting an element, list any child elements it can contain. Use a <section> element for this purpose.

Related Topics

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

References

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

Additional Information

Any supplementary information, usage tips, or frequently asked questions related to the element, attribute, or component can be included in an “Additional Information” section.