What is the typical organization of content in a DITA reference topic?

November 10, 2023
|By Bryan Tipper

The organization of content in a DITA reference topic follows a specific structure to present specific information in a clear and consistent manner.

A typical organization of content in a DITA reference topic should include a title, optional short description, body, sections, examples, and related information.

Title:

The title of the reference topic provides a clear and concise label for the concept or term being documented.

Short Description:

While not always necessary, a short description provides a brief summary or definition of the concept. It helps users quickly understand what the reference topic is about.

Body:

The body of the reference topic contains detailed information about the concept, term, or object. It can include text, tables, lists, and other elements to present comprehensive details.

Sections or Elements:

Within the body, the content is organized into sections or elements that cover various aspects of the concept. These sections can vary depending on the nature of the reference topic but often include attributes, properties, specifications, or related information.

Examples:

Reference topics may include examples to illustrate how the concept or term is used in practice. Examples help users better understand the context and application of the reference topic.

Related Information:

If applicable, a reference topic may include links or references to related topics, further reading, or additional resources for users seeking more information.

Example:


        <reference>
            <title>HTTP Status Codes</title>
            <shortdesc>An overview of HTTP status codes and their meanings.</shortdesc>
            <body>
                <section>
                    <title>1xx Informational</title>
                    <p>HTTP 1xx status codes provide informational responses to indicate that the request was received and understood.</p>
                    <ul>
                        <li>
                            <p><code>100 Continue</code>: The server has received the initial part of the request and will continue to process it.</p>
                        </li>
                        <li>
                            <p><code>101 Switching Protocols</code>: The requester has asked the server to switch protocols.</p>
                        </li>
                        <!-- More 1xx codes and descriptions -->
                    </ul>
                </section>
                <section>
                    <title>2xx Success</title>
                    <p>HTTP 2xx status codes indicate that the request was successfully received, understood, and accepted.</p>
                    <ul>
                        <li>
                            <p><code>200 OK</code>: The request was successful, and the server has returned the requested data.</p>
                        </li>
                        <li>
                            <p><code>201 Created</code>: The request has been fulfilled, resulting in the creation of a new resource.</p>
                        </li>
                        <!-- More 2xx codes and descriptions -->
                    </ul>
                </section>
                <!-- More sections for other status code categories -->
            </body>
        </reference>

In this example, the DITA reference topic documents HTTP status codes, providing a structured overview of different code categories and their meanings. The reference topic includes titles, short descriptions, body sections, and examples to effectively convey information about HTTP status codes.