DITA Reference Topics and Short Descriptions

Reference topics

Reference topics include a collection of facts. They provide detailed explanatory information in a structured lookup table or list format. They enable readers to quickly find a particular fact.

Facts could include such things as:

• Lists of parameters
• Lists of fields
• List of parts
• Syntax for a command

Guidelines for reference topics

Consider the following guidelines for reference topics.

• Describe one reference type of information per topic.
• Break up long reference topics into smaller chunks by categorizing the information.
• Organize the information to make it easy to look up and use—use sections, definition lists, and tables to make the information easier to scan.
• Format the information consistently – make patterns for the reader to follow so that they can scan the topics quickly.
• Use nouns in the title of reference topics.

Creating a reference topic

To create a reference topic 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.

Major components of a reference topic

The main elements that you use in a reference topic include:

The following image shows an example of the structure of a reference topic.

Tables and Definition Lists

DITA provides three types of tables:

• Regular (CALS) tables are the most commonly used and contains all of the features you would typically associate with a table.
• Simple tables cannot include a title and has more limited features.
• Properties tables are a three-column format that describes a property type, value, and description. A common use of a properties table is document fields for a software program in which you provide the field name, a description of the field, and any default values for the field.

Guidelines for tables

• Use specific table titles that describe the contents of the table.
• Make the tables easy to scan:
  • Name column headers that describe that succinctly and clearly describe the contents of that column.
  • Limit the number of columns.
  • Do not overload a table cell with too much text.
• Tables can be in all topic types.

Creating a regular (CALS) table

The following image shows an example of how a regular table looks within oXygen. Notice that it includes a title.

To create your table in oXygen, position your cursor where yiou would like to insert a regular table and complete the following steps:

1. Select DITA > Table > Insert Table.
   
2. In the Insert Table window, select CALS as the model.
3. Click the Checkbox next to title and enter a title for your table.
4. Specify the number of rows and columns.
5. Ensure that the checkbox next to Generate header row is checked.
6. Click OK.

Creating a simple table

To create your table in oXygen, position your cursor where yiou would like to insert a simple table and complete the following steps:

1. Select DITA > Table > Insert Table.
   
2. In the Insert Table window, select simple as the model.
3. Specify the number of rows and columns.
4. Ensure that the checkbox next to Generate header row is checked.
5. Click OK.

Note: Simple tables cannot have titles.

Creating a properties table

The properties table has a three-column format that describes a property type, value, and description. The following example (from the DITA OT documentation) shows an example of a properties table.

To insert a properties table, complete the following steps. Properties tables can only occur in reference topics.

1. From the Element list, select the <properties> element.
2. Position your cursor behind the <properties> start element and enter the <prophead> element.
   • proptypehd – the column head for the type of property
   • propvaluehd – the column heading for the property value
   • propdeschd – the column heading for the property description
3. Position your cursor behind the <prophead> and insert the following elements:
   • proptype – the type of property
   • propvalue – the value for the current property
   • propdesc – a description of the current property

Creating a definition list

A definition list the includes a list of terms and associated descriptions. It uses the:

• The <dl> element to contain the entire list.
• The <dlentry> to contain each term and definition combination.
• The <dt> element to contain the term being defined.
• The <dd> element to contain the description for that term.

The following example shows a definition list that includes three items.

To create a definition list within oXygen, complete the following steps.

1. In your topic, position your cursor where you would like the list to appear and insert a <dl> element.
2. Within the <dl> element, insert a <dlentry> element for each term that you need to define.
3. Within each <dlentry> element, insert the term within the <dt> element and the definition within the <dd> element.

Short Descriptions

The shortdesc element is used to:

• Introduce topics.
• Provide hover text for a cross-references to the topic.
• Produce the automated generated text for links to the topic.

Within a short description, you should:

• State the purpose of the topic
• Use complete sentences
• Avoid introducing list, figures, or tables in the short description
• Keep the short descriptions brief
• Do not include links in short descriptions

The following example illustrates a couple of uses of short descriptions in a webhelp output. When you hover your cursor over a table of content entry in the left panel, the short description appears in the box as hover help. In addition, the Cookbook page includes a automatically generated list of subordinate children located at the bottom of the page. In this list, it also include includes the short description for the topic under the link. Crafting well-written short descriptions according to guidelines can improve the usability and consistency of your documentation.

A well-written short description can help in search results. Include one in every topic so that all autogenerated link text and hover text is consistent