Task topics are the most important pieces of information in the whole document 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. Users want to be told what to do with a product; not how a product works. Don’t tell how your product works; instead show them what steps to take in using the product. Show, don’t tell. 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.
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 is to prevent 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 (give commands) sentences
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.