Skriftlig Info ➜ DITA publishing ➜ DITA topics ➜ DITA Task topic
Here is the "official" description from Oasis:
The strict task-document type supports the development of instructions for the completion of a procedure. [...] Tasks are the essential building blocks to provide procedural information. A task information type answers the "How do I?" question by providing precise step-by-step instructions detailing the requirements that must be fulfilled, the actions that must be performed, and the order in which the actions must be performed. The <task> topic includes sections for describing the context, prerequisites, expected results, and other aspects of a task.
Oasis: Task topic (strict task), [REF]
I choose to define a task topic like this:
A DITA Task topic is a stand-alone data module containing multimodal text. The module has a title and enough information to explain a specific procedure. A task topic must only explain one task, and this must be explained in an easy-to-understand manner with a fixed structure. Each action must be explained in the imperative tone with numbered steps. Each step in the procedure shall contain only one action and appear in the order in which they are to be performed.
TipUnder "DITA Elements" you can find a more detailed description of the elements used in a task topic. |
Task topics are the most important topics in a publication. They explain how readers should do something . The importance of task topics in DITA is based on the principle of task-oriented writing. That principle is based on the following propositions:
The content of the task topic must be written according to the following principles:
Normal practice is that a procedure should not contain more than a maximum of nine steps. If you get more steps than this, you should consider merging steps, establishing underlying steps (<substeps>) or dividing the procedure into two or more separate task topics.
|
It is important that our user manuals focus on what the product is supposed to do, i.e. the tasks the user wants it to perform for him. We must focus on procedures. |
TipIn technical documentation we uses the term task-oriented writing for a methodology where the information is organized as procedures to the greatest extent possible. These describe how a product should be used. The methodology is based on the recognition that the reader is primarily interested in knowing how tasks are done, and less interested in knowing how something works. Most of the products you buy are used for something specific. This applies to everything from consumer goods such as light bulbs and toilet paper to technically advanced products such as mobile phones and private cars. The key word is still use, every product must do one or more tasks for you. In the user manual, each task must be explained with one or more procedures. |
For the record, the DITA standard describes two different task topics; "General" and "Strict". As the names suggest, one is a bit "stricter" than the other. The main difference is that the "General" task topic allows additional <section> elements.
<title>
All task topics must have a title.
<shortdesc>
All task topics must have a "short description" that defines the context.
<prolog>
This element can be used to provide index information. Index information can also be inserted elsewhere in the topic.
<taskbody>
This element is used to collect all the information in the topic. See <taskbody>.
Of these elements, only <title> and <taskbody> are mandatory.
<prereq>
This is an optional <section> element used to describe the prerequisites; what the user needs to know, or needs to have, before the task can start.
This element shall not contain anything for the reader to do !
<context>
This is an optional <section> element used to convey background information. This information should help the reader understand the purpose of the task and what is achieved when it is performed correctly. The information in the <context> element should not replace conceptual information. If you have information that you think the reader can benefit from , you can include brief information about this. If the understanding of the task requires extensive conceptual information, reference must be made to a concept topic.
<steps>
This element provides a numerical list of the tasks to be done. See <steps>.
<result>
This optional <section> element is used to describe any results after the task is completed.
<example>
This optional <section> element is used to describe any example.
<postreq>
This optional <section> element is used to describe what the reader may need to do after the task is completed.
Of these elements, only <steps> is mandatory.
The elements built up from <section> elements can contain regular multimodal text, and the vast majority of standard DITA tags can be used.
The <steps> element has a very special structure. It can contain one or more <step> elements. Each of these contained one <cmd> element. After the <cmd> element you can use additional elements to elaborate on the action to be performed, present conceptual information, or explain any results of the action.
<step>
This mandatory element must contain an action. See <step>.
The <steps> element can contain many <step> elements. Each <step> element can use the elements listed here.
<cmd>
This mandatory element must contain the action that the reader must perform. The sentence in the <cmd> element must be written in imperative form with the verb first.
<info>
This optional element can be used to enter multimodal information. The element must not contain anything that the reader shall do.
<stepresult>
This optional element can be used to enter multimodal information. The element must contain text that describes the result of what was performed in the <cmd> element. The element must not contain anything that the reader shall do.
<substeps>
This optional element can be used to enter subordinate steps. <substeps> can contain a given number of <substep> elements. Each of these contains one mandatory <cmd> element as well as any <info> and <stepresult> elements. The <substeps> element cannot contain underlying <substeps>.
The <step> element can also contain other underlying elements, but they are not as widely used.
|
Remember that a well-written procedure uses only one sentence in each <cmd> element. This sentence explains what is to be done using imperative voice. All other information related to each <step> must be placed in the underlying elements. |
<step><cmd>Turn on the mains switch.</cmd>
<stepresult>
<p>The lamp is lit with green colour if everything is all right.</p>
</stepresult>
</step>
Creating a new DITA topic from a template
Creating a new DITA topic by duplicating an existing topic
Inserting a topic into a topic map
Inserting a topic into a bookmap
All external links open in a new window. I take no responsibility for information on external websites, even if I have linked to them. Please report links that do not work.
The information on this page represents my personal opinions and my understanding of the topic being described. Feel free to link to the page, but do not copy large parts of the content without permission. I take no responsibility for any errors, misunderstandings or missing information. I also take no responsibility for any mistakes you may make or cause as a result of incorrect or missing information. You are welcome to contribute with comments, relevant experiences or additional information. See Editor and contact information.