By Lisa Logan, Chapter Member
Editor's note: Read Lisa's other DITA articles at New Challenge: Learning DITA and A-Tisket A-Tasket: Task Topics in DITA.

Three months ago, I embarked on a journey to learn the basics of DITA. Here’s another log entry of my continuing DITA adventures.

In my last post, we covered the task topic. This article will describe concept and reference topics, completing our discussion of the three DITA topic types: task, concept, and reference.

Concept topics

What do concept topics do? They support task topics in that they give the user additional information that he or she needs to know before starting a task or in order to help them complete the task. You can find a great description of this in the book DITA Best Practices where this example is given: The task topic describes how to design web pages. The concept topic describes how web browsers find and display web pages.

So concept topics give you background information that helps you understand the process or even describes the process itself before you undertake it. Concept topics can be used to describe a system or product; to introduce tools; to explain features; describe benefits of a product; and to define terms more precisely or in greater detail than the average glossary entry. So concept topics support task topics. Concept topics are the bit players while task topics are the main players.

Guidelines for writing concept topics

• Describe one concept per topic.
• Create concept topic only if the idea has not been clearly covered.
• Distinguish task info from conceptual info. Don’t mix them.
• The amount of concept topics you’ll need really depends on the expertise of your user. That’s why task analysis is so important in preparing and planning your documents.
• Task titles are verb-based; concept titles are noun-based.
• When creating lists: Limit lists to seven items if items are long; limit lists to nine items if items are short.

Common DITA XML elements for concept topics

<title>
<shortdesc>
<conbody>
<section>
<sl>
<ul>
<dl>
<fig> and <image>
<term>

You can find a description and list of XML elements for concept topics here http://docs.oasis-open.org/dita/v1.2/os/spec/common/concept2.html#concept2 and also here http://docs.oasis-open.org/dita/v1.0/archspec/dita_spec_22_info_concepts.html.

So remember, concept topics define things, describe benefits, and outline processes. But they do not instruct!

Reference topics

Reference topics are used as even more backup for tasks. If the conceptual information is not enough, let’s call in for backup! Reference topics are go-to information that you need on an as-needed basis (such as a glossary). Let’s say that you’re learning about DITA and you want to know the most common XML elements used for reference topics. Then you’ve got a sidebar with a list of commonly used XML elements for reference topics like the one below. That’s a reference topic--information in the form of a visual cue such as a table or list. Tables and list make this information easy to scan. Reference topics can be lists of parts or tools needed to complete the task at hand.

Guidelines for writing reference topics

• Don’t write over one to two pages of reference topics. Break up the information into different tables or topics.
• Use visual cues that make the reference information easy to find. Tables, lists, and sections are visual cues useful for reference topics.
• When using tables, don’t use too many columns or “catch-all” columns. This makes the table difficult to scan for the facts the reader quickly needs.
• Don’t overload cells with text for the same reason.
• Use noun-based titles such as “The reference DITA topic element”.

To recap… Task topics focus on user goals and describe the steps in a process. Concept topics explain the ideas behind a process and give info needed before starting a task. Reference topics further support the task topic by giving a collection of facts that’s easily accessible to the user in the form of a list, table, or section.

Common DITA XML elements for reference topics

<section>
<refsyn>
<example>
<table>
<simpletable>
<properties>

Here’s a more comprehensive list of XML elements used for reference topics: http://docs.oasis-open.org/dita/v1.2/os/spec/common/reference2.html#reference2.

Now, I’m researching DITA maps and I hope to post about that in the future. If you’d like to get some hands-on experience with DITA, check out the DITA workshop that STC Carolina is offering October 18th. For more information about the workshop, go to Announcing the Chapter DITA Workshop.

Lisa Logan can be reached at lisalogan9 at gmail dot com. Read more articles by Lisa.