by JoAnn Hackos, PhD - President, Comtech Services and co-editor of DITA Specifications

The OASIS DITA Technical Committee has been having an interesting debate this month. The debate concerns the need for "glue text" in technical manuals. Glue text is defined as transitional information intended to inform readers of what has come before or comes after a particular procedure, description, or explanation. In topic-oriented authoring, which forms the basis for the DITA Model, transitional text has become problematic. If the goal is to write standalone topics that may be used in more than one context, where does one put the transitional text? Does transitional text belong in a topic by itself? Should it be built into a task, concept, or reference topic? Does transitional text belong in the map so that it does not encumber the standalone topics?

The more basic question that interests me, especially since I strongly espouse a minimalist agenda for technical information, concerns the purpose of that transitional text. Is it necessary at all? Does it have any actual effect on those who use the information we provide? Can we dispense with it entirely as an anachronistic reminder of a book-oriented structure that was imposed upon technical manuals by an accident of publication? Are our assumptions about the users of our text correct or an artifact of a book-publishing culture?

The supporters of transitional text argue that such text does not constitute standalone topics and, therefore, should not be written as DITA topics at all. They suggest, alternatively, that the transitional text be included in the DITA map. Clearly, such text does not fulfill the requirements of a DITA topic, as the supporters recognize. But including text in a DITA map is an uncomfortable solution because that placement suggests the text is questionable. In this discussion, we examine that questionable nature of "glue text" and consider how it might be rethought or handled more effectively.

Avoiding transitional text

I contend that transitional text plays no role in most technical manuals, being an unneeded relict of a book-oriented design. People using manuals for perform work do not approach a text in the way we assume they should, as a book to be studied with concepts to be learned. They are not readers but are users of information, reading only enough to reach a particular goal.

The DITA Technical Committee debate centered on the requirement of some corporate style guides for introductory sections of books, sections, and chapter that list the content of those chapters. You all recognize the presence of text that essentially forms an instructional objective:

"In this chapter, you will learn the following:

• How to make a call
• How to answer a call
• How to set up your list of contacts and phone numbers


...and so on."

Text of this sort is usually intended to prefigure the content of the chapter, serving, according to the theory, as an advance organizer for the reader. The transitional text also serves as a mini-table of contents for the subsection of a manual, often expanding upon the table of contents at the beginning of the manual by adding another level or two of headings.

Unfortunately, introductory text of this sort is not very effective as an advance organizer and seems to be routinely ignored by users looking for the task they need to perform. Introductory text that may be appropriate as an instructional precursor does not play the same role in text that is intended primarily as a reference rather than a learning tool. The list of upcoming content in a workshop or classroom setting provides a verbal advance organizer that is essential in an oral rather than a written setting. The prefiguring of the coming content allows the speaker and the listener to set the context for information that is by nature ephemeral. The listener cannot go back to review spoken text as he or she might easily do with written text. As a result, trainers or other speakers list what they will discuss and periodically remind the listener of where they are in the list.

"We have completed the discussion of making a call. Now, we will proceed with the second discussion, that of answering a call."

Transitional text of this sort seems unnecessary in a technical manual, particularly if users reference it only to perform a particular task. Our users are not reading the text in the same way that participants are attending to an instruction.

Understanding advance organizers

The introductory and transitional text provided in technical manuals is often referred to by the writers as "advance organizers." Advance organizers have been the subject of research in instructional design, beginning with David Ausubel's 1963 description of advanced organizers as a cognitive strategy to help students learn and retain information. Ausubel argued that students were better able to retain the content of a verbal lesson or the content of a textbook chapter if they were first provided with an advance organizer.

Ausubel noted that

"These organizers are introduced in advance of learning itself, and are also presented at a higher level of abstraction, generality, and inclusiveness; and since the substantive content of a given organizer or series of organizers is selected on the basis of its suitability for explaining, integrating, and interrelating the material they precede, this strategy simultaneously satisfies the substantive as well as the programming criteria for enhancing the organization strength of cognitive structure." (1963, p. 81).

Ausubel emphasizes that advance organizers are different from overviews and summaries which simply emphasize key ideas and are presented at the same level of abstraction and generality as the rest of the material. Organizers, he explains, "act as a subsuming bridge between new learning material and existing related ideas."

Here is an example of an advance organizer in a text about the solar system:

"Our solar system consists of the Sun, nine planets, about 70 satellites of the planets, and many smaller bodies including comets and asteroids (meteorites). The inner planets are those that are relatively close to the Sun: Mercury, Venus, Earth and Mars. The planets of the outer solar system are Jupiter, Saturn, Uranus, Neptune and Pluto. Thus Earth is the third planet from the Sun, and our position in the solar system helps to account for many of the characteristics of the Earth (e.g., chemical composition and density of Earth's rocks, our atmosphere, temperatures at the Earth's surface).

To address this Competency, we first consider the characteristics and description of the solar system, and its formation. Today, astronomers generally believe that the bodies in the solar system formed from a gigantic cloud of gas and dust; this is the nebular model or hypothesis. Then we investigate tools, including telescopes and spacecraft, used by astronomers to study the solar system and space beyond our solar system. For the second class covering this Competency, we study energy produced by our Sun and other stars, and consider use of stellar spectra to indicate motion in space, and the life-cycle of stars. With this overview of our solar system and space, we will look at current thoughts on the origin of the universe."

Note how the text prefigures the learning at a higher level of generality than the material in the text itself. This example appropriately sets the learning context and assists the reader in retaining the coming information.

If the advance organize is written as an instructional objective, it might sound much like the following:

"The purpose of this reading is to introduce you to the key elements of a Greek tragedy according to Aristotle.

When you complete this reading, you should be able to list without error the six elements of a Greek tragedy. You should be able to describe in writing Aristotle's conception of the plot, including all four of his descriptions."

An instructional objective states the behavior change the reader is likely to experience after reading the text.

Very few so-called advance organizers in technical manuals meet the criteria that Ausubel outlines. Rather, they tend to be simple lists of the titles of the upcoming content in a chapter or section of the manual. They function as tables of contents, not as advance organizer. Now, it may be somewhat useful to a reader of a manual to see a list of the coming content. However, my observations during much usability testing and contextual inquiry suggest that the assumption is mistaken. Either the information users ignore the advance organizers all together or mistake them for tasks and become confused.

In either case, they are unnecessary, merely filling a space required by an outdated style guide. From the perspective of topic-centered information design and minimalism, they are best left out completely. The chapter outline is not transitional text because it transitions nothing nor does it function as an advance organizer.

Developing real advance organizers

Occasionally, however, a group of topics may profit from a genuine advance organizer. Consider, for example, a group of tasks that should be performed in a sequence or exist in a more complex relationship to one another. An introductory discussion may be quite useful if it explains the overall process to be performed or prefigures the decision making inherent to perform a complex series of tasks effectively. Yet, one rarely sees such prefiguring in technical manuals because it requires a higher level of abstraction that the writers might not yet have achieved themselves.

An advance organizer of this sort is most likely a conceptual or process-oriented topic. It may include a flow diagram depicting the relationship among the coming procedural text. In any event, such an effective advance organizer should be developed as a standalone topic that can be included in a DITA map or not, as the user scenario requires.

Adding text between topics

Text between topics is designed to tie topics together by implying a sequence or a more complex relationship, a relationship that might be prefigured in an advance organizer. Writers, aligning their styles with instructional design and speech, suggest that they include text that glues one topic to another. Once again, much of the proposed transitional text ignores the user's agenda, which is often to find a standalone topic and perform a task or understand a concept.

In technical manuals that describe discrete, standalone tasks, transitional text is not only unnecessary, it adds clutter. Consider, for example, your cell phone manual. Each task represents a standalone instruction for performing a discrete action. Transitional text simply encumbers the reader and adds expensive extra words.

If the tasks are related rather than discrete, one may find some need for transitions. However, I recommend that the transitions be built into the topic themselves rather than treated as undefined words that should be added to the DITA map. If a task sequence must be performed in a particular order, as is the case with many installation or configuration procedures, the transitional text should be included as pre- or post-requisites. If the task is used in a context that requires no transition, the pre- or post-requisite can be omitted by using conditional text or a style sheet. If it seems best to present the workflow graphically, the graphic might be repeated from task to task with different elements highlighted to pinpoint the position of the task in the overall flow.

Summary

I recommend that information architects and developers seriously reconsider the role of transitional text in technical manuals. Certainly, some technical information requires transition, especially conceptual information that is designed to be read and learned. However, much technical information we provide in manuals is designed to be used rather than learned. As such, it requires neither prefiguring nor transitions to be effective. If we stop treating technical manuals as if they were textbooks and preserving the conventions and artifacts of text books in our style guides, we will more quickly achieve a more usable architecture that adds useful advance organizer and transitional texts only when required.