DITA Tasks and Concepts

Tasks

The task is the center of the user documentation world. All references and concepts within a deliverable should support completing required tasks. Tasks provide a sequential step- by-step instructions in a procedural format. Use a task when you want to describe how to do something

The following illustration shows the structure of a simple task. This example is taken from the examples for the DITA OT.

Guidelines for tasks

Some general guidelines for tasks include:

• Tasks should contain a single procedure.

• Use titles that start with verbs or “how to”.

• Each step should have an imperative statement within a <cmd> element.

• Write a concise short description that describes the task and its importance.

• Separate conceptual and reference information from the task.

• For complex processes or procedures, create a task that contains subtasks. That is, create a procedure that lists the high-level steps for the task in one topic. Then create a topic for each of the individual high-level steps.

Major components of a task

The following table lists the major elements that can occur within a task.

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE task PUBLIC "-//OASIS//DTD DITA Task//EN" "task.dtd">
<task id="task_wq1_31l_lj">
    <title>Banana Bread</title>
    <shortdesc><b>Banana bread</b> is a basic, reliable banana bread recipe. The perfect thing to do
        with over-ripe bananas!</shortdesc>
    <taskbody>
        <prereq>
            <ul id="ul_vpq_ncl_lj">
                <li>1½ cups white sugar</li>
                <li>½ cup butter, softened</li>
                <li>3 bananas (the riper the better), mashed</li>
                <li>2 eggs</li>
                <li>2 cups all-purpose flour</li>
                <li>½ tsp. baking soda</li>
                <li>⅓ cup sour milk or buttermilk</li>
                <li>¼ tsp. salt</li>
                <li>1 tsp vanilla extract</li>
            </ul>
            <note>
                <p>½ tsp. baking powder and ⅓ cup milk can be substituted for the sour
                    milk/buttermilk and baking soda.</p>
            </note>
        </prereq><context>To create banana bread, complete the following steps:</context>
        <steps>
            <step>
                <cmd>Preheat oven to 350°F (175°C).</cmd>
            </step>
            <step>
                <cmd>Lightly grease an 8 in x 4 in loaf pan.</cmd>
            </step>
            <step>
                <cmd>Combine all ingredients into a large mixing bowl. Beat well. </cmd>
            </step>
            <step>
                <cmd>Pour batter into pan.</cmd>
            </step>
            <step>
                <cmd>Bake on middle shelf of oven for 60 minutes, or until a toothpick inserted into
                    the center of the loaf comes out clean.</cmd>
            </step>
        </steps>
    </taskbody>
</task>

Major elements within a steps list

The <steps> element contains multiple <step> elements. Each step element consists of a <cmd> element, followed by a variety of other optional supporting element. Each step should consist of only a single user action.

Concepts

Concepts provide readers with clear and accurate background information they must know before they can successfully understand and use the product or service discussed in the document. Write concepts as descriptive text to answer the questions, what is it, what does it do, how does it work, and why is this important. Use concept topics to support task topic types.

Note: This example is taken from the examples for the DITA OT.

Guidelines for concepts

Consider the following guidelines for topics:

• Describe one concept per topic

• Use concept topics appropriately – don’t put task information or steps in a concept.

• Use noun-based phrases for titles.

• Write short descriptions that provide an overview of theconcept.

• Organize and chunk the information through the use of unordered lists, ordered lists, simple lists, and sections.

• Use graphics to illustrate concepts.

• Make sure to read Chapter 3 from your DITA Best Practices book for examples and more explanations.

Major components of a concept

Block- and phrase-level elements

DITA provides block-level and phrase-level elements to structure content within the topics

• Block-level elements: equivalent to paragraph elements in FrameMake or block elements in HTML. These elements appear on their own line in output (for example, <note> or <p>)
  
• Phrase-level elements: equivalent to a character element in FrameMaker or inline elements. They are applied to text within in a paragraph (for example, <b> or <uicontrol>)
  
• For detailed explanation of elements, see http://docs.oasis-open.org/dita/v1.2/os/spec/language_reference.html#language_reference.

The following table lists some of the more commonly used black elements.

<dl>
   <dlentry>
      <dt>User name</dt>
      <dd>Your user name for the system network.</dd>
   </dlentry>
   <dlentry>
      <dt>Password</dt>
      <dd>The password used to log into the system.</dd>
    </dlentry>
</dl>

<p><b>Butter</b> is a dairy product made by churning fresh cream.</p>

<ul>
   <li>First item<li>
   <li>Second items</li>
</ul>

<ol>
   <li>First numbered item<li>
   <li>Second numbered items</li>
</ol>

<codeblock>public class Hello1
{
  public static void Main()
   {
      System.Console.WriteLine("Hello, World!");
   }
 }  
</codeblock>             

<sl>
   <sli>phrase 1</sli>
   <sli>phrase 2</sli>
</sl>

<pre>This example
   keeps white space
   and line breaks</pre> 

<note type="tip">
   <p>1/2 tsp. baking powder and 1/3 cup of milk 
   can be substitued for the buttermilk and baking soda.</p>
</note>

The following table lits some of the more commonly used phrase-level elements:

<p>The dog is <b>not</b> a stray.</p>

<p>Please reference the <cite>Chicago Style of Manual</cite>.</p>

<p>Use the <cmdname>dir</cmdname> command to get the contents of the directory.</p>

<p>The statement <codeph>WriteLine('Hello World')</codeph> writes the specified text to the console.</p>

<step><cmd>Copy the <filepath>c:\uisettings.ini</filepath> 
           to the directory that you created.</cmd></step>

<p>Her name is <i>Claire</i>.</p>

<step><cmd>Select <menucascade><uicontrol>File</uicontrol>
           <uicontrol>New</uicontrol></menucascade>.</cmd></step>

<p> The following text will be subscripted: <sub>example</sub></p>

<p> The following text will be superscripted: <sup>example</sup></p>

<step><cmd>Click <uicontrol>Next</uicontrol> to continue.</cmd></step>

<step><cmd>Enter <userinput>Menu</userinput> to display 
           the menu for the device.</cmd></step>

<p>The <varname>username</varname> variable will show the user name on the web page.</p>

<p>The <wintitle>Preferences</wintitle> window shows the preferences for the application.</p>

oXygen tutorials for tasks and concepts

This section provides tutorials for tasks and concepts.

Creating a new task

1. Select File > New.

2. In the New window, expand Framework templates > DITA > topic.

3. Select Task [DITA/topic] and click Create.

   

4. Make sure that you have clicked the Author view at the bottom of your editing window. You must be in this mode to use the DITA menu.

   To show tags in this view, select DITA > Tag DisplayMode > Full Tags.

Create a new concept topic

1. Select File > New.

2. In the New window, expand Framework templates > DITA > topic.
   

3. Select Concept [DITA/topic] and click Create.

Inserting an image

1. Open your topic.

2. Positions your cursor where you want to insert the image.
   

3. Select DITA > Insert > Insert Image.
   
   

4. In the Choose image window, click the folder icon and navigate to the figure that you want to insert.
   

5. Click OK.

Publishing DITA topics in oXygen

oXygen uses the open source DITA toolkit to publish DITA topics.To create a PDF or XHTML version of the topic, complete the following steps:

1. Open your topic and select Document > Transformation > Configure Transformation Scenarios.
   

2. In the Configure Transformation Scenarios window, select DITA PDF and DITA XHTML and click Apply associated.

   Note: The open toolkit comes with many more output types.

3. Click on New and select DITA OT transformation to view them.