By Lisa Logan, Chapter Member
Editor's note: Read Lisa's introductory article on DITA at New Challenge: Learning DITA. “I DITA know that!”

Again, here we are with another corny title and more about my journey to teach myself DITA. This article offers the reader a basic understanding of what a task topic is along with a few tips on how to write an effective task topic. Task topics are one of three topic types in DITA.

• Task topic: one procedure
• Concept topic: defines or tells how a process works
• Reference topic: has one type of reference info that users might need as they perform tasks.

You should try to separate the three content types so users don’t have to sift through unnecessary information. For instance, if a user is looking only for the steps of how to bake a German chocolate cake, they don’t want extraneous concept or reference information such as the history of this cake in Germany or how it evolved throughout history to the current recipe. They only want the task topics which are the steps in baking the cake.

This article will focus on the task topic. We’ll cover concept and reference topics in upcoming posts.

Task topics are the most important pieces of information in many documents because they hold the information that users want most—instructions. Task topics spell out the tasks that are needed to complete the goal that the user wants to achieve. In a users’ guide, don’t just explain how the product works. Show the reader how to use the product. Plan ahead before setting out on a task topic writing binge by getting to know your users and their goals.

Here are some guidelines for creating task topics:

1. Only one procedure per topic.
2. Focus on user’s goals.
3. Keep your task topics clean-cut task-only info. Remove long conceptual and reference info from task topics.
4. Chop up long procedures into shorter subtask topics.

Below is a list of task topics XML elements that are specific only to task topics. In other words, they are not shared with other topics.

<prereq>
<steps>
<cmd>
<info>
<stepresult>
<stepxmp>
<postreq>

Other XML elements such as the paragraph <p> element can be used as any topic type.

Other rules to keep in mind when writing a task topic include:

1. Limit a task topic to only one <steps> element. This prevents the writer from adding many procedures into one topic. Don’t cheat around this by using the <ol> ordered list element to contain a bunch of tasks.
2. Use verb-based or “how to” language for task titles. For example, “Building a bicycle,” “Installing the wireless card,” and “How to build a bicycle”. Also, be consistent in your titling.
3. Use imperative sentences (give commands). For example, “Start the process by clicking the ENTER button.”
4. Limit yourself to ten steps or fewer per task topic.
5. Combine short steps.
6. Don’t nest more than one level of substeps.

DITA allows only one level of substeps in a task. To add more would make the task difficult to follow.

In the next post, we’ll cover what a concept topic is and give a few examples of common XML elements used for that purpose.

Check out OASIS’ definition and description of task topics at http://docs.oasis-open.org/dita/v1.2/os/spec/archSpec/dita_task_topic.html.

By the way, in an upcoming post, we’ll cover what OASIS is and all the fancy stuff they do.

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