Rethinking specializations

When I first started authoring in DITA, I thought the specializations were DITA requirements, or at least best practices. I ended up trying to make my content fit into concept and task topic types, often implementing complicated nesting, overloading certain elements with unintended info, and going out of my way to implement other workarounds to accommodate these topic types.

At some point, I realized that these specializations didn't really fit my information model. In fact, I don't think pouring content into task or concept models is a particularly good approach to creating content. Writers end up fragmenting their content into these different information types, dividing content that should be together into a million tiny little topics.

I instead prefer to use the base topic type rather than these specializations. Instead of using cookie cutter shapes to try to make information fit into, I think it's better to analyze the goal and construct the information users need appropriately. You can still emphasize a task-based approach without enforcing a structure that makes it cumbersome to add more than one list or an extended explanation at the beginning.

Additionally, using the base topic type is much easier to work with if you're leveraging any jQuery plugins. It also simplifies DITA authoring considerably, and results in a better output. Also, there is no research ever done to support DITA's specialized information types as being any more instructive than a general task-based approach.

So, save yourself some time. Skip the specializations and just write content with an action-oriented approach. Your DITA experience will be much less frustrating, and rather than trying to sort out the logic that restricts certain elements and their orders, trying to force-fit it to work with your content, you can instead focus on creating user-friendly content.

Concept topic types

Concepts are topic types for any information that doesn't involve task lists or reference information. Ideally you use concept elements to explain concepts, ideas, overviews, workflows, and the like.

Sponsored content

The basic structure of a concept topic looks like this:

- title
- shortdesc
- conbody
    - p (optional)
    - section
        - title
    - p
    - image
    - codeblock
    - etc.

Here's an actual sample:

<title>Keeping a clean house</title>
<shortdesc>Cleaning your house helps make your home comfortable and pleasant.
There are lots of strategies to consider when trying to maintain a clean home.</shortdesc>
 <conbody>
  <section><title>A place for everything</title>
  <p>The organizing principle of a clean home is to establish a place for everything.
Without a place, you cannot establish order in your house.</p>
  </section>

  <section><title>Everything in its place</title>
  <p>You must also define a strategy for putting everything its proper place.</p>
  </section>
 </conbody>

With concepts, each subsection is a section element. You can't nest section elements with each other, but you can nest concept elements inside each other. If you really need a third level, and you don't want to nest concept elements, you can add a paragraph with an outputclass that looks like a third level heading. (See DITA: Combining topics.)

Task topic types

Task topic types have robust options for including information, results, and other details with each of the steps.

Here's the element structure of the task. This outline shows what tags are allowed at each level.

-task
-title
-shortdesc
- taskbody
     - prereq
     - context
     - stepsection
     - steps
          - step
               -cmd
               - info
                    - note
                    - image
                    - codeblock
               - stepxmp
               - stepresult
               - choices
               - substeps
     - result
     - example
     - postreq

Here's a full working example of a task: 
<task id="task_123">

    <title>How to wash dishes</title>

    <shortdesc>Washing dishes helps keep your kitchen clean and orderly.</shortdesc>

    <prereq>Before doing the dishes, you will need soap and gloves.</prereq>

    <taskbody>

        <context>
            <p>Washing dishes properly reduces bacteria and frees up the dishware available for you for eating. If you approach dish washing in a logical, efficient manner, the task can be enjoyable and fun. </p>
        </context>

        <steps>
            <step>
                <cmd>Put on headphones with appropriate entertainment options.</cmd>
                <info>Some people find that doing dishes in silence is therapeutic, but most do not. Adding an entertainment option can make dishes significantly more of an escape.</info>
            </step>

            <step>
                <cmd>Fill the sink with warm water.</cmd>
            </step>

            <step>
                <cmd>Get the scrubby warm and soapy.</cmd>
                <info>
                    <note type="note">Make sure you don't use an abrasive scrubby for delicate glassware.</note>
                </info>
            </step>

            <step>
                <cmd>Put on rubber gloves.</cmd>
                <stepxmp>
                    For example, you might use yellow Latex gloves.
                </stepxmp>
            </step>

            <step>
                <cmd>Scrub clean the dishes in soapy water.</cmd>
                <stepresult>The dishes will be clean but soapy.</stepresult>
            </step>

            <step>
                <cmd>Rinse the dishes by doing one of the following:</cmd>
                <choices>
                    <choice>Spray them with a sprayer.</choice>
                    <choice>Dunk them in a separate division of the sink that contains clean water.</choice>
                </choices>
            </step>

            <step importance="optional">
                <cmd>Dry the dishes with a rag.</cmd>
            </step>

            <step>
                <cmd>Put away the dishes in the appropriate cupboards.</cmd>
                <info>
                    <image href="cupboards.png" placement="break"/>
                </info>
            </step>

            <step>
                <cmd>Stake similar dishes inside each other for maximum space efficiency.</cmd>
                <substeps>
                    <substep>
                        <cmd>Nest the cups inside each other.</cmd>
                    </substep>
                    <substep>
                        <cmd>Stack the plates on top of each other.</cmd>
                    </substep>
                    <substep>
                        <cmd>Spoon the spoons, and nest the forks as well.</cmd>
                    </substep>
                </substeps>
            </step>

        </steps>

        <result>Congratulations, you've totally finishes doing the dishes. Now make sure that your spouse knows how hard you've worked.</result>

        <postreq>Now you're ready to wash the counters and mop the floors.</postreq>

    </taskbody>

</task>

As you're working in Oxygen, if you're in the Text view, type < and wait for the prompt to show you the available tags at that level. You can use your arrow keys to move up and down to see descriptions of each of the elements.

Most of the tags are self-explanatory, but a few are worth explaining. The cmd element is where the heart of the instruction lives -- it's the action verb for the instruction. The cmd element is a single block level element and doesn't allow many other elements inside it (but does allow image, codeph, menucascade, uicontrol, and other elements.

Any time you need to elaborate more with additional information, notes, code samples, or other details, add this additional information inside an info element after the cmd element. You can add many elements inside the info element, such as p, image, codeblock, and more.

If you use the importance="optional" attribute on a step element, the output will show (Optional) before the step.

If you have multiple options for a step, use the choices element.

Reference

The reference topic type is for storing reference information, such as extensive tables, lists, or other information that is used as support for a task. Reference topics are also designed for API information.

There are some tags specific to reference topics that aren't available elsewhere, such as a refsyn and properties table. The following examples come from the 1.2 DITA spec on the reference topic type.

Here's an example of how to use the refsyn element: 
<refsyn>
    <synph>
      <var>object</var><delim>.</delim><kwd>Font</kwd><delim>.</delim>
      <kwd>Bold</kwd><delim> = </delim><var>trueorfalse</var>
    </synph>
  </refsyn>
Here's a sample properties table: 
<properties>
<property>
      <prophead>
          <proptypehd>Oil type</proptypehd>
          <propvaluehd>Oil brand</propvaluehd>
          <propdeschd>Appropriate use</propdeschd>
      </prophead>
     <property>
      <proptype>Primary oil</proptype>
      <propvalue>A1X<propvalue>
      <propdesc>Appropriate for one-cylinder engines</propdesc>
    </property>
    <property>
      <proptype>Secondary oil</proptype>
      <propvalue>B2Z</propvalue>
      <propdesc>Appropriate for two-cylinder engines</propdesc>
    </property>
  </properties>

I don't use reference topics very much, but it may be that my content doesn't seem to call for it. I don't quite get what the properties table provides that a regular table doesn't provide. The only difference seems that you can generate a table with different styles for the different columns, and therefore customize its appearance to look different from that of other tables.

Glossary topic types

Creating a glossary involves creating glossentry topics, referencing the glossentry topics via keys, and compiling a glossary of terms in a DITA map.

First create each glossary entry topic using the glossentry topic type. The glossentry topic requires just two elements:

<glossterm>OT</glossterm>
<glossdef>Open Toolkit -- This is what processes DITA into the various outputs.</glossdef>

There are additional elements available in the glossBody tag if needed.

Next, create a ditamap file that will contain all of your glossary entry topics. You could put this in your main ditamap, but it's easier to manage it if the glossary map is separated into its own file. Add keys for each of the terms. The keys are like short references for the glossary reference. 
<map>
 <title>Glossary</title>

 <glossref href="ot.dita" keys="opentoolkit" />
 <glossref href="ide.dita" keys="ide"/>

</map>
In your main map file, reference your glossary ditamap. In this example, my ditamap containing all the glossary entries is called glossary_entries.ditamap: 
 <mapref href="glossary_entries.ditamap" processing-role="resource-only"/>
In regular topics where you want to link to the glossary entry, refer to the glossary entry like this:

  <p>You can use the <term keyref="opentoolkit">Open Toolkit</term> to process your dita files.</p>

The term will have a link to the glossary entry topic and also show a tooltip with the glossary definition.

To compile a list of glossary terms in your main table of contents, add references to the glossary entry topics just like any normal topic references: 

 <topichead navtitle="Glossary" chunk="to-content">
  <topicref href="ot.dita"/>
  <topicref href="ide.dita"/>
 </topichead>

Topic size limitations

Topics should be substantial enough to help a users complete his or her goal. However, there are a few topic size limitations with DITA that might seem to limit your ability to put all the information you need in a topic.

Task limitations. For task types, you can have only one task list per task element. If you have multiple task lists, you have the following options:

  • Split the tasks into separate files. If warranted, combine the tasks through your map file. If the tasks are each pretty meaty, leave them as separate files.
  • Nest task elements inside of each other. This might be useful if you have a process that involves multiple subtasks and each of the subtasks are short. See DITA: Combining topics for details.
  • Use a concept type topic and use regular ol and li list formatting rather than using steps. If your lists are light and short, the traditional list formatting might work just fine.

Concept limitations. For concepts, you can have an unlimited number of section elements per topic. However, you can't include nested sections (third-level headings). If you need a nested section, here are your options:

  • Nest concept elements inside each other.
  • Create separate concept files and combine them through a map.
  • Add an outputclass attribute to a p element (and select an output class that you will style in your webhelp stylesheet to look like a heading level 3),

Related information