Exercise 7: Creating DITA reference topics

In this exercise, you'll use the DITA standard for reference topics. The exercise will also focus on:

  • working with DITA simple and normal tables
  • working with definition lists
  • writing well-constructed short descriptions

Note: This exercise references the recipes that you developed for your first project as content. If you have other content that you want to work with instead of your recipes, you can use that content. However, ensure that your content uses the reference elements correctly and that you include at least three reference topics. Ensure that you read chapters 4 and 5 of the DITA Best Practices book. Note that DITA topics have the DITA extension.

Step 1: Create a DITA reference topic for each task topic.

In this assignment, you will create a reference topic for each recipe that defines the ingredients. To create new DITA reference topics in oXygen, complete the following steps:

  1. Select File > New.
  2. In the New window, expand Framework templates > DITA > topic.
  3. Select Reference [DITA/topic] and click Create.
  4. Ensure that each reference topic has a <title> and a <shortdesc> element that introduces the topic.
    • The title of each topic should be something like Ingredient descriptions for recipeName.
    • Ensure that the short description follows the best practices described in chapter 5.
  5. Delete the contents of the <refbody> element. You do not need the example of <refsyn> or <properties> elements for this exercise.

Each reference topic should provide a brief definition of each ingredient in your recipe. These definitions do not need to be detailed – I’m not grading you on the contents of the definition, but on the reference structure. You will use a different type of structure within each topic.

Step 2: Use a table within a reference topic.

In your reference topic for the first recipe, use a regular table to contain the definitions for your ingredients. To create the table, complete the following steps:

  1. Ensure that you are using the Author view in your reference topic so that the DITA menu appears.
  2. Position your cursor within the <refbody> element and select DITA > Table > Insert Table.
  3. In the Insert Table window, select CALS as the model.

  4. Click the Checkbox next to title and enter a title for your table.
  5. Specify the number of rows equal to your number of ingredients. Ensure that the columns value is set to 2.
  6. Ensure that the checkbox next to Generate header row is checked.
  7. Click OK.
  8. In the header row for the first column, insert the word Ingredient. In the header row for the second column, insert the word Definition.
  9. In the first column of the table, enter an ingredient in each row and add a corresponding definition in the second column.
  10. Validate and save that topic.

Example:

Step 3: Use a simple table within a reference topic.

In your reference topic for the second recipe, use a simple table to contain the definitions for your ingredients. To create the table, complete the following steps:

  1. Ensure that you are using the Author view in your reference topic so that the DITA menu appears.
  2. Position your cursor within the <refbody> element
  3. In the Insert Table window, click simple as the model.

  4. Specify the number of rows equal to your number of ingredients. Ensure that the columns value is set to 2.
  5. Ensure that the checkbox next to Generate header row is checked.
  6. Click OK.
  7. In the header row for the first column, insert the word Ingredient. In the header row for the second column, insert the word Definition.
  8. In the first column of the table, enter an ingredient in each row and add a corresponding definition in the second column. Do this for each ingredient that you need to define.
  9. Validate and save that topic.

Example:

Step 4: Use a definition list within a reference topic.

In your reference topic for the third recipe, use a simple table to contain the definitions for the ingredients. To create the definition, complete the following steps:

  1. Position your cursor within the <refbody> element.
  2. Insert a <section> element.
  3. Position your cursor within the section and insert a <dl> element.
  4. Within the <dl> element, insert a <dlentry> element for each ingredient that you need to define.
  5. Within each <dlentry> element, insert the ingredient name within the <dt> element and the definition within the <dd> element. Do this for each ingredient that you need to define.
  6. Validate and save that topic.
Example: 
<dlentry> 
   <dt>vanilla extract</dt> 
   <dd> 
      <p>
            <b>Vanilla extract</b> is alcohol containing 
            flavor (vanillin) from the vanilla bean.</p> 
   </dd> 
</dlentry>

Step 5: Create PDF and html versions of the topics

To transform the XML into PDF and html versions, complete the following steps:

  1. Open your topic and select Document > Transformation > Configure Transformation Scenarios.
  2. In the Configure Transformation Scenarios window, select DITA PDF and DITA XHTML and click Apply associated.

oXygen uses the transformations that come with the DITA open toolkit to produce renditions of the topic.

Step 6: Zip your topics and turn them in

In a ZIP file ("yourName-referenceTopics.zip"), include the three reference topics . (You do not need to include your PDF or HTML versions.) Your DITA topics should validate against the DITA DTDS correctly and the elements should be used appropriately. Upload the assignment.