Do We Really Need All that Glue?

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.


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.

Share your perspective on this article with author, JoAnn Hackos, and see what others think in our Transitional Text forum. Also weigh in on our poll.

This issue provides an opportunity to discuss an alternate method for addressing problems in structured markup. Let me restate this issue as two questions:

  1.  does transitional, or foreshadowing, text ever provide value to the reader?
  2.  if so, how should DITA support such a concept?

The answer to the first question is most certainly "Yes, transitional text does provide value in specific deliverable types and media." It is the prerogative of authors to best support their audience. DITA, as a solution, would be remiss to make exclusionary decisions for its audience in such cases. Obviously, DITA cannot be all things to everyone, but flexibility in addressing problems exists in multiple places within an XML solution, as I’ll explain later.

Before moving to the second question, it is important to reinforce the validity of your premise: while providing value in some contexts, in others, this type of transitional text is utterly useless. Thus, we must consider the contextual dependencies of when this type of content provides value.

Personally, I agree with much of your position, but as you point out, there is a great deal of debate, and DITA’s role is not of instructor but as a tool set that enables authors to achieve their goals. Basically, this is one of those holy wars that can be gracefully side stepped.

The second question, whether a topic or map should explicitly include transitional text, is with equal certainty "No." This answer is inherent in the concept of a markup; DITA should instead use the meta data collected about a topic to enable such functionality. Everything required to provide transitional text and lists exists in the markup today. So the question then becomes "how do we realize this desired result without affecting everyone?"

If it is truly an advance organizer that meets Ausubel’s criteria, then it should be contained in a standalone topic, where it does not hinder arbitrary organization of other topics. To optimize reuse, authors must defend their content so that it can be organized arbitrarily. Whether or not arbitrary organization is ever practiced, it should be a goal of DITA to provide maximum flexibility. Part of this content defense is on the author with prudent use of topics, but a part of it resides with the architects of the XML system.

In mid 2000, I helped two co-workers, Jason Willebeek-LeMair and Mark Wilgus, develop an XML solution that was similar to DITA. We dubbed the system NXS. While others helped with tool development, the core of NXS was developed by these two extraordinary individuals. I’m unable to recall originator of each idea, so I’ll refer to the collective:  "we did this", "our solution", etc.

As with the concept of an "index range," we proved that foreshadowing information could be derived from the topic type and target deliverable type and required no extra markup. What pollutes many of today’s markups and solutions is the narrow focus of "where" in the system a problem should be solved. Many authors and developers reach for additional markup address most problems.

However, many problems can be addressed abstractly, and uniformly, by boosting meta data inspection in the XSLTs and other post-processing of a deliverable type. To illustrate this concept, let’s consider what applicable meta data exists about each topic. In this case, the topicreftypes, title, abstract, shortdesc, and position in a map relative to other topics can used provide for some excellent transitional text. The key here is that the deliverable type (output type) is what should determine whether transitional text is generated during transform. Just as the transform of a deliverable type might ignore some markup irrelevant to its medium, it can just as easily construct new content that is derived from the populated markup.

As an example, let’s consider the case you presented, whether desirable or not:

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

The information in brackets can be derived from the title of the topic and the map. Therefore, at the end of a topic, the transform could include (if the deliverable type required it), the static text outside of the brackets. I’ve provided the logic for this in a sort of pseudo code:

  • If a sibling of current topic exists after this one, then include the following text:
    "We have completed the discussion of [current topic’s title (lowercased)]. Now, we will proceed with the [topic counter + 1] discussion, that of [title of next topic (lowercased)]."
    Else...[something else]

The conditional tests can evaluate any DOM nodes, such as siblings, children, topic-level nodes, etc. The important points are that the data exists already and that the XLSTs can isolate, or expose, this context-dependent information. The same can be done for mini-tables of content, which we did for the children of specific types of topics in NXS. We went so far as to vary the static content based on the position and end deliverable, such as "This <section/chapter/book/topic> discusses the following:"  Whether abstract summaries were included depended on whether it was the preface to a book or merely a chapter. In the end, topic reuse among our book-based deliverables and help system deliverables increased because the introductory topics were not tainted by the deliverable methods: the XLSTs took care of that for us.

This approach to problem solving provides additional flexibility in the system, allowing each deliverable type to solve those problems specific to their domain. At the same time, the markup and content does not become burdened with unnecessary markup and content. The result is that the system, the markup, and the solution are more flexible, easier to learn, and easier to maintain.

To summarize, DITA should not add markup for this type of arbitrary content, but it should defend the markup by showing users how to get what they want by extending the XSLTs logically.

I think you are right that transitions are not often required in order for content to be useful. However, the real challenge may not be reconsidering the role of transitional text in technical manuals, but rather, the role of technical writers in creating them. Are we creative literary folk or common commodity workers cranking out useful content snippets for cash? This articles serves as a good starting point for such a discussion.

Changing the way we work in order to make content more structured, streamlined, interoperable and machine-readable is the end goal, but may be the most difficult challenge we face as an industry. Anecdotal research, premature as it may be, indicates as many as one in four technical writers are unable -- or unwilling -- to write modular content appropriate for reuse. 

Does that mean we ought to abandon the effort to improve the value and reusability of the content we create? Certainly not! But what will we do with those of us who don't -- or won't -- master writing for reuse?

Food for thought or just a bunch of rubbish? You decide.

Scott Abel
Content Management Strategist
The Content Wrangler


I think you meant your question to be rhetorical (“Does that mean we ought to abandon the effort to improve the value and reusability of the content we create?”) or perhaps just that the answer was obvious (“Certainly not!”). I’m not sure it is that obvious. Let me share my anecdotal experience.

Several years ago I went down the reuse path. The content was eLearning. The reuse evangelicals were ADL and their bible was SCORM. We spent a lot of money creating “reusable” content only to learn that 1) people didn’t reuse it and 2) we spent a lot of money creating the content in a reusable way. We eventually determined, “It’s better to get it used once quickly than reused not at all.”

Actually, for us, the real power of SCORM (for you, think DITA) emerged when we “forgot” about reuse and started focusing on the tools to author and display the content. Then, our development efficiencies increased (in ways you wouldn’t believe) and the sophistication with which we presented the content dramatically improved as well.

So, maybe those writers who “won’t” convert may be in an environment where “reuse” isn’t that important (yes – there are such places) and they’re just seeing a bit further down the track. Maybe others who “won’t” convert will need to move to places where content isn’t reused (they need not despair however if they don’t see the value of reuse).

Maybe, just maybe, there are places where you “ought to abandon the effort to improve the… reusability of the content we create.” When people get to that point and they start thinking about what they’re doing differently (i.e., not reuse, but presentation), then you’ll see the real power of DITA emerge.

I attended the STC conference in Philadelphia last month. The presentations around DITA show that we’re still in our infancy. Vendors and presenters were, for the most part, talking about the basics of authoring content. The output being discussed, primarily, was print or page-based. I suspect we have a few years yet to push the envelope in these areas. The excitement will be when the performance support people and the DITA people get together and we really see “interoperability” in the way content is presented – when we see sophisticated content presentations (yes, there’s some of this with the current “help” systems – but again, we haven’t done much with those designs for 15 years now).

Andrew Teasdale

andrew underscore teasdale at yahoo dot com


Responsibility is not the 'price' of freedom but its reward.

Transitional text, as you here define it, is not an artifact of book design. It is a product of cognitive function. What you here call transitional text serves as an anticipatory trigger--that is, it prepares the brain to contextualize, and thus recognize, what is to follow. And that is why it is also a cornerstone of public speaking and visual arts, as well as publishing. Eliminating it drastically reduces comprehension & retention.

The problem here is not with the text, but with the architecture. Surely we can come up with suitable framework definitions and tags? In the SDK (software development kit) business we do this in essence all the time, by specifying required precedent and following functions--or, in plain language, prerequisites and postrequisites.

The solution is not to eliminate transitional text. The solution is to specify how to standardize its construction, and then adopt suitable standards into the architecture.

I think there are really two topics munged together here - transitional text and advanced organizers.  Transitional text is text written to smooth the transition between topics, and is, I believe, an artifact of print that is rarely helpful in topic oriented documentation .  Advanced organizers have some pretty powerful functions, including helping readers prepare for what they are going to learn and helping them effectively skip content they are not interested in.  Advanced organizers are not transitional text.

Pre- and post-conditions aren't, in my opinion, transitional text either.  Pre-conditions are similar to text of the form, "Don't follow this procedure unless you have already done ...".  Post-conditions are similar to text of the form, "Now that you've completed this step, you can [should] do ...".  Those elements are already in the DITA spec (prereq, context, result, postreq).  They are a required part of a  procedure, not a transition from a previous topic.

Transitional text that is basically a mini table of contents should be banned from all writing.  I can look at the real table of contents or skim the chapter if I want that information.  It's mind numbingly boring to the reader and just encourages them to skip all introductory material.  Plus it's difficult to maintain.  If you really feel you need it, do something similar to what the Idiom FO plugin does - create a mini-toc for each chapter.


Steve Anderson

I think you make an excellent distinction. I'll just add that the "mini-toc" version of an advanced organizer - think a simple overview topic - can actually still be quite useful in an online context. For example, a task overview that provides a summary of the subtasks in it provides a useful search destination that the individual subtasks might not. And higher-level tasks/topics are hopefully more likely to match user mental models and goals, compared with lower-level tasks/topics which are more likely to match system models and features.

In DITA, overview/container topics get link summaries of their children generated by default based on the map organization, so maintenance is also not an issue. 

I think overview topics are some of the most useful navigation aids you can include in a Web site or help set - they function both as search targets and as link hubs for users finding their way via link browsing. And I definitely agree that they don't really belong in the category of transitional text.

Michael Priestley Focus Areas: BPEL | DITA | ebXML | IDtrust | OpenDocument | SAML | UBL | UDDI
OASIS sites: OASIS | Cover Pages | | AMQP | CGM Open | eGov | Emergency | IDtrust | LegalXML | Open CSA | OSLC | WS-I