Chapter 7. Topic Specialization Tutorial

Goal: Define a new structural specialization of the base <topic> element type that supports the creation of FAQ (frequently asked question) topics.

Topic specialization generally requires defining a number of new element types at different levels in the element hierarchy, as opposed to domain specialization, which can be as a simple as defining a few new phrase-level element types.

The main reason to create structural specializations is to provide more-specific markup that reflects your local business requirements or the nature of your information. For most technical documentation applications, the value in specializing reference and task topic types is usually pretty obvious, because these are information types that work best when they directly reflect the details of the things being documented, specific editorial rules for how tasks should be structured, or the needs of other information systems that consume reference and task information (such as interactive task support systems).

Tip: DITA 1.2 introduces a new configuration feature, constraints, which allows you to modify content models without doing specialization. This allows you to reserve specialization for those requirements that truly require new markup. Before DITA 1.2 you also had to use specialization just to define more-constrained versions of base content models even when you weren't changing the meaning of the markup itself. This is no longer necessary in DITA 1.2. See Topic Constraint Module Tutorial.

For reference information, it is usually useful to define specialized reference topic types that directly reflect the objects being documented. For example, if you're documenting sprockets it probably makes sense to have a specialization of "reference" called "sprocket" or "sprocket-definition" that has specialized <section> elements that reflect the specific sets of properties or characteristics that sprockets have (tooth properties, shaft properties, material information, manufacturing notes, etc.).

For tasks, you may have specific editorial rules for how tasks should be constructed, rules that are more constraining than the base DITA rules for tasks (which are already pretty constraining). 1

Because conceptual information is, by its nature, more generic, there is usually less need, or less obvious need, to specialize from <concept>. For example, the topics for this tutorial are all generic concepts (although they use a specialized domain for identifying mentions of XML constructs). However, there are still many good reasons to specialize concept topic types.

One strong reason to specialize from <concept> is to create element types that reflect specific levels in a governing organizational taxonomy where the taxonomy is an integral and invariant aspect of the information. Another reason would be to provide different more-specific concept element types that are familiar to your authors or that reflect a particular editorial style for presenting conceptual information. For example, in the case of this tutorial, the FAQ topic type is based on concept but has been specialized to provide a clear "short answer/long answer" distinction, as well as disallow base types that we don't want to allow in FAQ topics (abstract in this case). In addition, having a specialized type for FAQ lets us apply FAQ-specific styling to the topics for presentation.

Note that specializing <concept> to reflect specific hierarchical levels within a traditional document, e.g., chapter, section, subsection, is normally not a good idea, because it binds a given topic to a specific level, making it harder to re-use or re-organize the topic in other contexts. Rather, if you want markup that directly reflects specific hierarchical levels, you should use map specializations, such as the standard <bookmap> or the DITA for Publishers publication map domain.

The only exception to this rule that I can think of is when you have an editorial policy that requires title-only topics (that is, topics with no body) to satisfy specific levels in a governing hierarchy (that is, a governing, invariant, taxonomy). In that case, it can make sense to define specializations of <concept> or <topic> whose names reflect the taxonomy or hierarchy level and that don't allow either <body> or nested topics (meaning that they only serve to be used from maps within a hierarchy of topic references). However, the value of this type of topic is dubious given that <topichead> elements within a map are sufficient to establish the hierarchy and provide the necessary titles.2

Note that you are not required to specialize from <concept>, <task>, or <reference>. You can specialize directly from <topic> or from a more-specialized topic type. The concept/task/reference model makes sense in the context of technical documentation where it reflects a well-established writing practice. But it is not always sensible for other uses of DITA. For example, in the context of Publishing, most content either does not naturally map to one of those three types or those distinctions simply aren't relevant (e.g., within a novel). In that case it can make sense to specialize directly from <topic>. For example, the DITA for Publishers vocabulary includes the topic types <article>, <chapter>, <part>, <subsection>, and <sidebar>, all specialized directly from <topic>, because they are intended to represent content at its most generic. The topic types simply provide a more obvious mapping to the basic document components Publishers would expect to see in any Publishing XML application.

1 DITA 1.2 defines a more generic base task type, which provides more opportunity to create specialized tasks that are different from the more-constraint DITA 1.1 <task>.
2 DITA 1.2 also clarifies the fact that topicheads can processed as though they referred to title-only topics.