Skriftlig Info ➜ DITA publishing ➜ DITA topics ➜ DITA Concept topic

DITA Concept topic

Here is the "official" description from Oasis:

I choose to define the concept topic in this way:

In a way, you can say that a concept topic gives the reader information that is "necessary to have" to understand the product. A reference topic conveys information that is "nice to have". This is information that the reader does not strictly need to use the product, but is useful for those who want more detailed information. You who must place the information in one of the two categories. It is useful to discuss this in your professional environment to establish guidelines.

A concept topic is easy to use because the structure is open. The information can be presented with all relevant DITA elements, with the exception of those specific to the task topic.

A DITA concept topic is structured as follows.

<title>

All concept topics must have a title.

<shortdesc>

All concept topics must have a "short description" that defines the context.

<prolog>

This element can be used to insert index information. Index information can also be inserted elsewhere in the topic.

<conceptbody>

This element is used to collect all the information in the topic. See Structure for <conceptbody>.

Of these elements, only <title> and <conceptbody> are mandatory.

The structure in <conceptbody> is open. The basic elements can be placed in random order without important restrictions. It is not useful to explain all the elements here. The most common elements used are:

<p>

<p> is a paragraph that can contain one or more sentences. <p> can be inserted directly under <conceptbody>.

<ul>

<ul> is an unordered list, also called a "bullet list". It can contain one or more points. <ul> can be inserted directly under <conceptbody>. <ul> lists can be nested to create multiple levels. You can also put <ul> lists inside <ol> lists and vice versa.

<ol>

<ol> is an ordered list. It can contain one or more numbered points. <ol> can be inserted directly under <conceptbody>. <ol> lists can be nested to create multiple levels. You can also put <ol> lists inside <ul> lists and vice versa.

It can be tempting to use the <ol> element to create a numbered list, and then call this a procedure. This is not permitted, and it is a direct violation of the entire philosophy that DITA represents. Procedures shall and must be placed in task topics. Concept topics must only contain explanatory and descriptive information.

In some places it is useful to replace the numbers in the list with upper or lower case letters, or perhaps Roman numerals. This is done using attributes, and must be implemented in the style sheet. For example, it is a good idea to use letters when referring to details in an illustration. A list of A, B, C etc. cannot be misunderstood as a procedure.

<dl>

<dl> is a list to explain terms. It is often used to list choices in a menu. It can contain one or more terms. <dl> can be inserted directly under <conceptbody>.

<div>

<div> is used to group underlying elements under a main element. This is useful for profiling (conditional text) and reuse.

<section>

<section> is used to group underlying elements under a main element. This is useful for profiling (conditional text) and reuse. <section> can have a <title>, and the element can be divided further using <sectiondiv> and/or <div>elements.

<example>

<example> is used as the name suggests to describe an example.

If desired, the <conbodydiv> element can also be used to collect information. A <conbodydiv> has the same properties as a <conbody> element. The use of <conbodydiv> and <section> allows you to collect information that belongs together. This can be very useful because any profiling of a <conbodydiv> element will also apply to everything inside. You can also use such elements to collect information in a library, and reuse all the information at the same time.

Similarly, <sectiondiv> and/or <div> can be used inside <section>.

What is important about a concept task is the constraint attached to the <conbody> element. This restriction works as follows:

• Before inserting a <section> or <example> element, you can use most other standard DITA elements.
• After you have inserted a <section> or <example> element, you can only insert more such elements.

It may sound like this is a limitation that makes use difficult, but this is not the case. In fact, it is quite logical. For example, if you insert a <section> element with a title, and inside this insert plain text, how can the reader see that the content of the <section> element ends and "other" information begins? The title that is used first in the <section> element will apply to all information down to the next title.

Here is an example that describes a (very) short Concept topic.

This example imagines a concept topic that contains a title, a single sentence (Body text), and then a <section> with a title and two sentences. When you work in an XML editor, the code will rarely look like this. You also don't have to remember which elements you can use where, because the editor will help you with that.