One of the advantages of DITA's design is that you can develop a library of topics for assembly into different types of document across various media. But  some documents or outputs may benefit from transitional text.  Many of the posts here allow that it can be be useful for forms that are linear, either logically or physically -- forms such as training documents or printed books.  If we are to realize the full benefit of DITA, we need to ensure that it can accommodate transitional text when called upon to do so.

This is something of a "holy war," and not just between advocates of different approaches to technical writing.  At a deeper level, I believe this is a contest between older "linear" forms of thinking related to so-called "Gutenberg" media, and newer "associative" forms related to electronic media. Neither of these modes of thought is  "correct." Both are valuable. We need to preserve the possibility of transitional text for those who want to use it. If we can find a way to do so with DITA, then DITA will be stronger -- and so will we.
 

One of the things that caught my attention when DITA was brand new was the thing where the shortdesc for each link gets pulled up into the summary topic. I had been doing that manually for years, and then started scripting it in my own kludgy fashion, but the way it was built right into the DITA architecture pretty much made DITA indispensable as soon as I found out about it.
To me, that's what transitional text is. The summary topic is where you "tell them what you're going to tell them," and because this is built into the architecture, the forewarning doesn't just reflect the content that's to come, it _is_ that content. The skill part then becomes analyzing and mapping the content in such a way that it makes sense to a user who starts from the summary and proceeds through the nested topics _and_ to the user who jumps right into one of the nested topics. The beauty of DITA to me is how all the infrastructural stuff is taken care of for me behind the scenes and I'm free to concentrate on the actual information itself.

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 transition, 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, 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.

Blaine McNutt

P.S. I appologize for the double post.

It seems to me that transitional text is only important when readers are expected to follow a linear path through the material.

I don't believe this is the case with user manuals, like the cell phone guide mentioned in the article. No one is going to read the cell phone manual from start to finish; when it is used, it will be to find information about a task or function the reader cannot discern from the phone's interface itself. In a case like this, transitional text serves no purpose, nor is there any need for an advanced organizer or anticipatory trigger to prepare the reader for material to come.

However, I have found that while user manuals are primarily intended for reference and their content is "designed to be used rather than learned," there is often an assumption (at least for complex software products) that the manual can also be used to learn the product.

I think this is the central problem. A well-designed document can serve only one primary purpose. DITA is clearly designed for creating reference materials, where information is split into small stand-alone topics that users access in an arbitrary order to locate the information they need. This is not altogether unlike a phone book or dictionary (neither of which, to my knowledge, tend to include a lot of transitional).

When a software manual is also expected to serve as a means of learning a product, then we start trying to modify the core design to accommodate a secondary purpose, one that requires clear topic sequencing, transitional text, anticipatory triggers and other devices. And, I would argue, the manual becomes less effective at serving its original purpose.

The answer, I think, is to recognize that learning and reference are different and somewhat incompatible goals. We should not try to stretch our architecture or our document design to accommodate learning; rather, we should create separate documents (or other instructional devices) specifically designed to facilitate learning--documents with their own design built around an alternative architecture.

If our manuals focus on their primary purpose, then there's no use for transitional text, and the question of how to implement this content through DITA becomes moot. I wouldn't use DITA to create a linear text; it wouldn't work very well. I think it's a better architecture because of that.

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 a cornerstone of public speaking and visual arts, as well as publishing. Eliminating it drastically reduces comprehension and  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.

-----Dr. Jennifer R. Pournelle, LEAD Technologies, Inc.

This is a great subject to explore. JoAnn gives compelling arguments against using chapter outlines in topic-based technical documentation. I'd like to open that discussion up a little more.

As JoAnn points out, an advanced organizer (or, as I think of it, "tell 'em what you're gonna tell 'em" text) serves a different purpose in training than in technical documentation. The relevant distinction, I think, lies in whether users will encounter the topics in a fixed sequence, as in instructor-led training, or whether they'll be navigating through the topics in unpredictable ways. In other words, is the writer supporting the learning or the finding of information?

There seems to be no question of the value of  "tell 'em what you're gonna tell 'em" text in training contexts. The real question focuses on documentation, in particular on chapter outlines. As JoAnn puts it, "The chapter outline is not transitional text because it transitions nothing nor does it function as [a genuine] advance organizer." Besides, as she points out, users ignore chapter outlines or, worse, "mistake them for tasks and become confused."

As someone who has encouraged the use of chapter outlines for years, these arguments give me pause. Not that I ever thought of chapter outlines as transitional text. I don't think of them that way. I think of these lists as navigation aids, especially important in chapters that consist of standalone topics. Since topics are only as useful as they are findable, I like to give people various ways to find the topics they're looking for. Specifically, I like to provide a good index (an endangered species), a master table of contents, and also chapter outlines so that users can maneuver to the desired topic regardless of where they are in a book.

Book. There, I said it. That word gives me away. I work in print, where the chapter outline serves a navigational purpose that can perhaps be fulfilled in more effective ways online. Unfortunately, those ways of navigating are unavailable on the old-fashioned page.

By the way, I am picturing chapter outlines in print either with or without page numbers. Either way, such lists reveal the sequence of the topics in that section, facilitating jumping.

For me, the important question regarding chapter outlines is this: For a given medium, do these chapter outlines help users find the topics they want?

I hold that the answer, for topic-oriented print documentation, is often yes. I can believe, as JoAnn says, that users often ignore chapter outlines, just as they often ignore indexes. I've ignored chapter outlines myself. But I've also found them helpful. I can't imagine them confusing people in a print manual. Unless research really proves the opposite, I would argue that chapter outlines can serve as navigation aids in print documentation where chapter length justifies them.

I like JoAnn's discussion of developing "real advance organizers" as conceptual or process-oriented topics in their own right. Done well, such topics can serve as both learning and navigational aids, even as quick references. They are often absent in documents that could benefit from them.

As you read the article on transitional text, consider how your readers use your information. Are your assumptions about their reading behaviors correct? Do they start from the beginning of a book, chapter, and section, and read until the end? Or do they look for one item and neglect its surroundings?

Let me and other participants in this forum know more about your concerns with regard to transitional text in technical manuals.

JoAnn  Hackos