Concept Topic

Concept topics contain the essential and complete information needed to understand a product, process, system or any other conceptual or descriptive information. Concept topics answer the question: “What is...?”.

Typically, concept topics explain what something is, how it works, the components it consists of, how they can be combined, and so on. In other words, they help readers map their knowledge and understanding to the tasks they need to perform and to provide other essential information about a product, process, or system.

Concept topics typically contain paragraphs with text, definitions, and supporting images. Content in concepts can also be organized in sections. Use sections only when necessary. Rather than sections, opt for multiple topics to increase reuse when it makes sense to do so. For example, in long topics that need additional subdivision for content scannability.

Note: Once a section or example element is added to a topic body element, only additional sections or examples are allowed. Sections and examples can not nest, meaning that only one level of subdivision is possible.

Do not use ordered lists (ol) in concepts to list a sequence of actions. Use the task topic instead.

Concept Topic Structure and Common Elements

Here is a sample concept topic in the Content Editor with a description of each element.

Figure 1. A sample concept topic that discusses the concept of bird songs.

This concept topic contains a short description, paragraph, example, unordered list, and two sections.

concept element (concept)
- Referred to as the root element which is the top level or parent element of a topic.
- Present in the topic by default.
- Contains all other elements of the topic.
Referred to as the root element which is the top level or parent element of a topic. Present in the topic by default. Contains all other elements of the topic.
title element (title)

Essential part of every topic that navigation and search heavily rely on. Also present in elements like section, figure, and table.
short description element (shortdesc)

Provides content for link previews and search engines. We recommend always using it. Can be tricky to write but Etto can help there. Shouldn't be longer than about 60 words. If needed, it can be expanded with the abstract element. Both elements compliment each other. See [link to abstract].
concept body element (conbody)

Present in concept topics by default which means you do not need to insert it when working in Heretto CCMS. Required to add the main (or body) content to the topic. Specific to the concept topic. Can contain elements like p, example, ul, and section.
paragraph element (p)

A block element. Contains text and inline elements. Cannot contain other block elements which are elements that start from a new line, like figure or note. We recommend always wrapping text with p instead of adding it directly in elements like li, entry, or note as it ensures correct DITA syntax. The CCMS can ensure correct syntax for you. Do not remove those p elements present in elements like li, entry, or note.
example element (example)

A block element. Provides an example or supporting information that illustrates the concept explained in the topic. Examples cannot be nested (example within an example). Once an example is added to the conbody, only additional examples or sections can follow.
unordered list element (ul)

A block element. Lists items whose order is not important. If order is important, use ordered list [link]. Unordered lists can be nested (ul within an ul) to create hierarchy in an unordered list.
Section Element (section) (optional, not recommended)

A block element. Comes with an optional title. Can contain other block elements like p, fig, and table. Sections cannot be nested (section within a section). Once a section is added to the conbody element, only additional sections or examples can follow.

Here is what the DITA source looks like for this topic:

<concept id="concept-5744" xml:lang="en-us">
    <title>Bird Songs</title>
    <shortdesc>Bird songs are complex vocalizations used to attract mates or defend territories.</shortdesc>
    <prolog>
        <author translate="no" type="creator">Heretto User &lt;user@heretto.com&gt;</author>
    </prolog>
    <conbody>
        <p>Bird songs vary widely among species, from simple songs that are genetically imprinted to complex songs that are learned over a lifetime.</p>
        <example>
            <p>Flycatchers know their songs from birth:</p>
            <ul>
                <li>Flycatcher songs are simple sequences of notes.</li>
                <li>Flycatcher songs never vary but are unique to each member of the Flycatcher family.</li>
            </ul>
        </example>
        <section>
            <title>Variability and Learning of Bird Songs</title>
            <p>While some birds are born with the capacity to sing their species-specific songs, many birds learn their songs from adult tutors. This learning process is most evident in songbirds, where young birds often go through a critical learning period during which they mimic and practice the songs of their elders, leading to a rich diversity of song patterns within a species.</p>
        </section>
        <section>
            <title>Function of Bird Songs</title>
            <p>Bird songs serve multiple functions in avian communication. One primary purpose is to attract mates, where males often use complex songs to showcase their fitness and genetic quality. Additionally, bird songs are used to establish and defend territories, warning other birds of an occupied area.</p>
        </section>
    </conbody>
</concept>

Under maintenance

Heretto Help

Concept Topic

Concept Topic Structure and Common Elements

Footer Section

Our Support Team is here to help