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 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. Information types work best when they directly reflect the details of the things being documented, the editorial rules for how tasks should be structured, and the needs of other information systems that use the information (for example, interactive task support systems).
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 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 when that 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 and to
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. Instead, 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 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 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.
These topic types also reflect the simplest topic specialization, one that changes
only
the topic root element, leaving all other elements unchanged. For DITA for Publishers
this reflects the need to distinguish chapters from articles as business objects,
and
people expect to find these topic types in a publishing vocabulary.
<task>.