Designing a topic hierarchy

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 we 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:
  • Starting
    • Engine principles (concept)
    • Starting the engine (task)
    • Engine specifications (reference)
An alternative approach would be to group concept topics, task topics and reference topics, resulting in a high level structure such as:
  • Car Concepts
    • Starting
    • Driving
    • Stopping
  • Car Tasks
    • Starting
    • Driving
    • Stopping
  • Car Reference Information
    • Starting
    • Driving
    • Stopping

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 used?
  • How much information will each node contain?
  • What nodes will connect to what other nodes?
  • What sort of links will be used?
  • What entry points are needed?

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 child topics.
1 Miller, G. A. (1956). The magical number seven, plus or minus two: Some limits on our capacity for processing information. Psychological Review, 63(2), 81-97.