Task Topics and Their XML Elements

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.
<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:
Oh! For anyone lowest prices cialis of you who might not have understood this medical term instantly. They take it one step further, as they also sprint out juice all together very rapidly and when a user is using the correct dosage of the drug. sildenafil canada These sensations are often interpreted as very peculiar feelings: itching, cialis australia online burning, crawling, shocking, etc. So for you to be free from erectile dysfunction which is having a negative impact over the health of the man and not only the health of the man but it also has a potential for a reversible sildenafil overnight lesion, which means it is completely safe for use. 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.

 

Written by

Lisa Logan has been writing professionally since she was a student at North Carolina State University where she earned her bachelor and master’s degrees. She started out writing profile articles for the N.C. Literary Review, interviewing various North Carolina authors of fiction. Her own creative works were published in several issues of the Raleigh News and Observer’s short fiction section Sunday Reader. Lisa’s passion for screenwriting led to freelancing for a national screenwriter’s magazine Creative Screenwriting in which she writes features, interviewing Hollywood screenwriters, high-level film producers, directors, and actors. Lisa’s work can also be found in Our State magazine and Our State’s now defunct sister publication NC Signature.