[General] Task Topic
Task topics provide step-by-step instructions for completing a specific procedure or achieving a goal with a product, system, or process. They provide a structured and systematic approach to presenting information, making it easier for users to follow and complete the steps involved. Task topics answer the question: “How do I...?”.
Key characteristics of a task topic:
-
Focuses on how to complete an action
-
Includes prerequisites and context when needed
-
Contains a series of sequential or unordered steps
-
May include optional steps or alternate approaches
-
Often contains post-task results or examples
-
May include post-task actions
General task topics provide several advantages over strict task topics through their more flexible structure:
- Less Strict Content Model
-
The general task topic type has a more relaxed content model for the
<taskbody>element compared to the strict task topic. This looser structure enables more flexibility in how a task topic is organized. - Additional Elements
-
The general task model permits two additional elements within the task body:
<section>and<steps-informal>. The<steps-informal>element uses<ol>and<ul>elements, which are less strictly defined than the<step>element, making it simpler to convert numbered lists from legacy content. - Flexibility in Element Order and Quantity
-
Unlike the strict task model, the general task model permits multiple instances and varying order for the
<prereq>,<context>, and<section>elements within the<taskbody>. In the strict task model, these elements have a specific order and quantity (e.g., only one<prereq>must precede<context>). - Facilitates Migration of Unstructured Content
-
The less strict content model of the general task topic can make it easier to migrate loosely structured tasks from other sources into DITA. When converting unstructured content, it might be simpler to convert numbered lists to
<ol>elements within<steps-informal>than to individual<step>elements. - Supports Diverse Task Specializations
-
The more relaxed base task topic type enables the creation of a wider variety of specialized tasks, including those that might not have formal markup for individual steps. The general task content type is specifically designed to accommodate task specializations that differ from the standard DITA task content type.
Task Topic Structure and Common Elements
Task topics follow a logical structure with required and optional elements, organizing procedural information in a systematic way that guides users through completing specific actions with a product, system, or process.
This task topic contains a short description, prerequisite, context, steps, choices, result, as well as a few inline elements.
-
Task Element (
task) (required): The root element of all task topics -
Title Element (
title) (required): Clear indication of the task's purpose -
Short Description Element (
shortdesc) (optional, recommended): Brief overview of the task's goal -
Taskbody Element (
taskbody) (required): Contains the main (or body) content of the task -
Prerequisite Element (
prereq) (optional): Required conditions before beginning the task -
Paragraph Element (
p) (recommended): We recommend always wrapping text withpinstead of adding it directly in elements likecontext,prereq, ornoteas it ensures correct DITA syntax. -
Context Element (
context) (optional): Background information to help readers understand the purpose and scope of the task before they begin. -
Steps Element (
steps) (required): A container that organizes the sequential actions a user must perform to complete a task, with each step contained in a separate step element. -
Step Element (
step) (one or more): Contains a single action or instruction that a user must perform, optionally includingnote,hazardstatement,info,substeps,stepxmp,choices,choicetable, andstepresultelements to provide additional details or guidance. -
Task Topic Structure and Common Elements (required): Contains the primary action or instruction within a step, expressing precisely what the user needs to do.
-
Result Element (
result) (optional): The expected outcome of a completed task. -
Postrequisite Element (
postreq) (optional): Contains actions or tasks that users must complete after finishing the main task.
step).The DITA source for this topic:
<task id="task-6667">
<title>Signing in to MobileView</title>
<shortdesc>Learn how to sign in to the MobileView application through the ClusterControl server.</shortdesc>
<prolog>
<author translate="no" type="creator">Heretto User <user@heretto.com></author>
</prolog>
<taskbody>
<prereq>
<p>Ensure you have your username, password, and the name of the server that you want to connect to.</p>
</prereq>
<context>
<p>After signing in, you can sign out and disconnect from a particular project without closing MobileView. Signing out without closing the application is helpful if you plan to sing in again using different credentials.</p>
</context>
<steps>
<step>
<cmd>To open MobileView, click <menucascade><uicontrol>Start</uicontrol><uicontrol>All programs</uicontrol></menucascade> Thunderbird MobileView.</cmd>
</step>
<step>
<cmd>In the MobileView window, do one of the following:</cmd>
<choices>
<choice>Enter your MobileView username and password.</choice>
<choice>Sign in using your <tm tmtype="reg">Windows</tm> user account by selecting the <uicontrol>Windows</uicontrol> selection button.</choice>
</choices>
</step>
<step>
<cmd>In the directory field, enter the name or IP address of the main StormCluster ClusterControl server. Click <uicontrol>Sign In</uicontrol>.</cmd>
</step>
</steps>
<result>
<p>You are signed in to MobileView. You can sign out by clicking <menucascade><uicontrol>Home</uicontrol><uicontrol>Sign Out</uicontrol></menucascade>. If you do not sign out manually, you will be signed out automatically after a period of inactivity. </p>
</result>
<postreq>
<p>After signing in, verify that the dashboard shows the correct user information and project data.</p>
</postreq>
</taskbody>
</task>