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.
The basic structure of a concept topic looks like this:
Here's an actual sample:
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.
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
element is where the heart of the instruction lives -- it's the action verb for the
cmd element is a single block level element and
doesn't allow many other elements inside it (but does allow
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
cmd element. You can add many elements inside the
info element, such as
codeblock, and more.
If you use the
importance="optional" attribute on a
element, the output will show (Optional) before the step.
If you have multiple options for a step, use the
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.
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
glossentry topics via keys, and compiling a glossary of terms in a DITA
glossentrytopic type. The glossentry topic requires just two elements:
There are additional elements available in the
glossBody tag if needed.
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:
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.
taskelements 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
concepttype topic and use regular
lilist 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:
conceptelements inside each other.
- Create separate concept files and combine them through a map.
- Add an
outputclassattribute to a
pelement (and select an output class that you will style in your webhelp stylesheet to look like a heading level 3),