Learning DITA

Free DITA training

Free DITA training

Adding basic elements to a concept topic

Some of the most commonly used elements in a concept topic include:

<p>

paragraph

<ul>

unordered list

<ol>

ordered list

<note>

admonition

These elements were covered in the Introduction to DITA course. This lesson gives a brief review of these elements and shows how to add them to a concept topic.

Practice
  1. Continue using the file lesson1/l_new_concept_start.dita.
  2. Inside the <conbody> element, add a <p> element and add content to it as shown in the following example: 
    <?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE concept PUBLIC "-//OASIS//DTD DITA 2.x Concept//EN" "concept.dtd">
<concept id="my_first_concept">
   <title>Wild duck species</title>
 <conbody>
<p>North American wild ducks belong to one of the following categories:</p>
   </conbody>
</concept>

    The <p> element is for body text. It can be used inside the <conbody> element as well as inside many of the elements that <conbody> contains.

    Note:

    Use the <p> element for any body text that does not need a more specific element tag. As you will see in examples throughout this course, we recommend using the <p> element to tag text inside list items, notes, and table entries. <p> elements are needed for list items that are several paragraphs long, and wrapping single items in the <p> element keeps them all consistent.

    The <p> element you just created introduces the next element: an unordered list.
  3. After the <p> element, add a <ul> element and add content to it as shown in the following example: 
    <?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE concept PUBLIC "-//OASIS//DTD DITA 2.x Concept//EN" "concept.dtd">
<concept id="my_first_concept">
   <title>Wild duck species</title>
  <conbody>
...
<ul>
<li><p>Dabbling ducks</p></li>
<li><p>Diving ducks</p></li>
<li><p>Sea ducks</p></li>
<li><p>Whistling ducks</p></li>
<li><p>Swans and geese</p></li>
</ul>
   </conbody>
</concept>

    Note:

    If you are using a DITA editor, the editor may insert an ID attribute on the <ul> element for you automatically.

    The <ul> element is for unordered or bulleted lists.
    The <ul> element can only contain the <li> element, and it must contain at least one.
    Each <li> element contains the text for a bulleted entry in the list. In this example, the <li> elements follow the best practice of wrapping a <p> element around the text.
  4. After the <ul> element, add an <ol> element with an introductory <p> element as shown in the following example: 
    <?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE concept PUBLIC "-//OASIS//DTD DITA 2.x Concept//EN" "concept.dtd">
<concept id="my_first_concept">
   <title>Wild duck species</title>
   <conbody>
...
 <p>The longest species of dabbling ducks in North America are:</p>
<ol>
<li><p>Northern pintail</p></li>
<li><p>Mallard</p></li>
<li><p>American black duck</p></li>
</ol>
   </conbody>
</concept>

    Note:

    If you are using a DITA editor, the editor may insert an ID attribute on the <ol> element for you automatically.

    The <ol> element is for ordered or numbered lists.
    Like the <ul> element, the <ol> element can only contain <li> elements, and it must contain at least one.
    In this example, each of the <li> elements follows the best practice of wrapping a <p> element around the text.

    Note:

    Use the <ol> element only to show that the list items should appear in a certain order, not to create step-by-step instructions. For step-by-step instructions, use the task topic instead.

  5. After the <ol> element, add a <note> element and add content to it as shown in the following example:
    Video: Creating a note in DITA
    <?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE concept PUBLIC "-//OASIS//DTD DITA 2.x Concept//EN" "concept.dtd">
<concept id="my_first_concept">
   <title>Wild duck species</title>
  <conbody>
...
<note><p>Although the northern pintail is the longest dabbling duck, the mallard 
is generally considered the largest because of its heavier body weight.</p></note>
   </conbody>
</concept>

    The <note> element is used to add admonitions, such as notes, warnings, or cautions, to the concept topic. The <note> element you just created follows the best practice of wrapping a <p> element around the text.
  6. Check your file lesson1/l_new_concept_start.dita against the sample file lesson1/l_new_concept.dita.
Practice
  1. Open the file lesson1/l_new_concept_exercise_start.dita and use it to convert the following content into DITA:

    Content strategy and business goals

    The issues to consider are:

    • The real cost of low-cost documentation
    • How to create an efficient content development process
    • Whether high-quality documentation can lower the cost of technical support
    • The most cost-effective way to share technical content across the enterprise

    Note: Ignoring content can have cost implications across the organization.

    To implement your project and improve your chances of success, we recommend following this sequence:

    1. Identify and interview stakeholders.
    2. Establish implementation goals and metrics.
    3. Define roles and responsibilities.
    4. Establish timelines and milestones.
    5. Build the content creation system.
    6. Convert legacy content.
    7. Deliver content.
    8. Capture project knowledge.
    9. Ensure long-term success.
  2. Check your file lesson1/l_new_concept_exercise_start.dita against the sample file lesson1/l_new_concept_exercise.dita.
Contributors