How is the <data-about> element used to specify metadata in DITA?

November 10, 2023
|By Bryan Tipper

The <data-about> element in DITA metadata is used to capture information about a content element’s relationships to other topics or resources. It serves as a means to specify and document the connections, associations, or dependencies that a particular content element has with other elements or resources within a DITA document or topic map.

The <data-about> element is used for relationship documentation, connection information, and content structure.

Relationship Documentation

The primary purpose of the <data-about> element is to document and specify relationships. It allows content creators to describe how the content element is related to other topics, concepts, or resources.

Connection Information

Within a <data-about> element, various sub-elements can be used to provide information about the nature of the relationship. For example, the <linkinfo> sub-element may contain details about the type of link or relationship, while the <conrefinfo> sub-element can specify conref-related information.

Content Structure

<data-about> elements can be applied to DITA topics, maps, or other elements, enabling the documentation of relationships at different levels of the document hierarchy.

Example

A DITA topic titled “User Manual” contains information about a software application. Within this topic, there may be a section about “Keyboard Shortcuts” that references specific shortcuts for different features. The <data-about> element can be used to document the relationship between the “Keyboard Shortcuts” section and the referenced features: 


        <topic>
            <title>User Manual</title>
            <body>
                <p>This user manual provides instructions for using the software application.</p>
                <!-- Relationship documentation using <data-about> -->
                <data-about>
                    <!-- Documentation of a link or reference -->
                    <linkinfo type="cross-reference">
                        <title>Keyboard Shortcuts Section</title>
                        <description>Section describing keyboard shortcuts for software features.</description>
                        <targetref href="keyboard_shortcuts.dita"/>
                    </linkinfo>
                    <!-- Additional relationship information, if needed -->
                </data-about>
            </body>
        </topic>

In this example:

  • The <data-about> element is applied to the “User Manual” topic to document relationships within the topic.
  • Within the <data-about> element, the <linkinfo> sub-element specifies that a cross-reference exists, providing a title, description, and a reference to the “Keyboard Shortcuts” section in another DITA topic (“keyboard_shortcuts.dita”).
  • This relationship documentation helps content creators and readers understand the context and connections between different parts of the documentation. It aids in navigation, cross-referencing, and content comprehension.