A well-designed topic hierarchy will make the reader's task of
finding information in a publication easier.
Structuring the content of a document is one of the most important steps
in the authoring process. It is here that you establish the logical
relationship between topics, and add context to the set of topics.
Some theoretical considerations to make when deciding on the structure
of topics include the following.
- The human mind can
manipulate about four concepts at a time.
- Humans make better decisions
when presented with groups of seven choices (Miller's Law)1.
Translated to a document structure, this points to an ideal document
structure made up of
parent topics with seven
child topics at every level, and no more than four
generations of topic families.
A three level hierarchy with seven topics per menu will permit 343
pages. Four layers of ten topics permits up to 10,000 topics, which is more
than enough for even the largest manuals.
The human mind thinks in associative, rather than linear, patterns. Thus
"get on the wrong track", and
"forget how we got onto this subject". The human brain stores
information in this way also, by finding a similar experience and associating
it with the current experience ("this tastes like vinegar").
In DITA, concept information is separated from task and reference
information. This makes it more difficult to structure a document purely around
the goals of the reader, unless the nature of the information allows the
creation of standard sets of one concept, one task and one reference topic.
Such an information model would permit a TOC structure such as:
- Engine principles
- Starting the engine
- Engine specifications
An alternative approach would be to group concept topics, task topics
and reference topics, resulting in a high level structure such as:
- Car Concepts
- Car Tasks
- Car Reference Information
In reality, however, most information models do not have such a
repeatable structure. More likely is that there will be a concept topic that
has three or four related task topics, with a reference topic that might be
associated with a dozen concepts.
The best structure for a particular document is not something that can
be easily prescribed; it is the responsibility of the author to devise a
logical structure that will support the aims of the deliverable document.
You should consider the following questions when designing a TOC and a
structure for your topics:
- What level of detail will be
- How much information will
each node contain?
- What nodes will connect to
what other nodes?
- What sort of links will be
- What entry points are
Two more specific guidelines to adopt are:
- Designing your structure
with a single node at the top of the tree hierarchy (a
"mother-of-all-topics") from which all other topics branch. This
helps ensure logical
breadcrumb links and other navigation pathways.
- Do not use topic headings
(topichead elements). Instead, use stub or summary topics:
topics that contain only a title. The publishing process can automatically
build the content of such stub topics based on the short descriptions of its