Stem sentences in technical communication have long been considered a standard practice to introduce new content, especially steps in a task. The task stem sentence, generally consisting of a partial sentence such as “To start the machine:” is not supported by any explicit DITA element in the DITA Task information type.

The question is: Should DITA include a stem sentence element in the Task information type?

[By the way, that was a stem sentence.]

According to Bloom’s Taxonomy of Critical Thinking and Writing Effective Learning Objectives/Outcomes, published in 1956 by Benjamin Bloom, a stem sentence is a partial sentence, usually the beginning noun and verb, that introduces a bulleted list. It is called a stem sentence because it is part of a sentence that is completed by the content of the bulleted list. A typical stem sentence might be: “In this chapter, you will learn:” followed by a bulleted list of the items you will learn.

In technical documentation, stem sentences of this type are used to introduce a set of steps in a task.

To start the engine:

1. Pull out the throttle

2. Pump the gas pedal

3. Push the ignition button

Nothing wrong with that structure if it didn’t result in unnecessary wordiness in the document, a violation of the spirit of minimalism. The minimalist agenda suggests that unnecessary words decrease the likelihood that the reader will read any of the words. As a result, experts often recommend removing the stem sentence introducing steps in a task.

In a DITA task, the standard structure requires a task title, followed optionally by pre-requisites and context in the form of paragraphs, lists, tables, and more. After these content units, the DITA task body provides a set of steps. Unless you insert the stem sentence as a paragraph at the end of your context information, there is no explicit place to put it.

However, the stem sentence promotes redundancy. Writers argue that they must use the stem sentences despite the redundancy because it is required by their style guides. As a result, you get structures like the following:

<title>Starting the engine</title>

<context>To start the engine:</context>

<steps><step><cmd>Pull out the throttle.</cmd></step></steps>

Looks pretty ridiculous with nothing in between the title and the stem sentence.

Writers argue, however, that sometimes there is valuable, even essential information to present between the title and the step. You may have a pre-requisite that includes a warning or caution or a list of equipment. You may have contextual information that explains more about the task to be done so that the user understands the reasoning behind his or her actions. Generally, this contextual information should be kept reasonably short in the task. For more context, readers should be sent to a Concept topic.

As the pre-requisite and contextual information grows, some writers and editors argue for a stem sentence to repeat the task title. Others argue that this practice is unnecessary because the user knows by the numbering that the steps are at hand. The argument for the stem sentence grows as proponents argue that they often writer procedures that contain multiple tasks under a more general heading. For example, they may have several sequential tasks that must be performed in order to complete an installation. Why not use one large task to accommodate the subsets with stem sentences to divide the sets from one another?

One contributor to a stem sentence discussion on the DITA-users mailing list made the following astute observation:

“If I were organizing that, I'd write the ‘Rotating Objects’ text as a topicgroup title in the ditamap, then have a topic for each of those procedures that has a title and a procedure - no stem sentence for any of them. If I really felt I needed intro material, I could create a topic for "Rotating Objects" explaining why a user would want to rotate objects, or that there are multiple ways to do it, but I don't think that'd be needed in this case.”

Another contributor noted:

“I'm also of the mind that topic titles can effectively eliminate the need for stem statements. I think stem statements are a legacy of long book chapters where suddenly a procedure can pop up in the middle of a long, abstract topic. In a book context, you possibly need some way to introduce a shift in implicit content type. With short, minimalistic, dedicated topic types, the title is likely close by and can do the job of introducing the topic properly.”

The original reason stem sentences were added to word processing files like MSWord or later to desktop publishing systems like FrameMaker related to the fact that both of these systems had problems with numbering (some still do). Some writers used stem sentences to introduce the steps in a task so that the steps would correctly start renumbering with 1. Without the stem sentence, a second set of steps might continue the numbering of a previous set of steps in the same discussion.

The stem sentence was lilkely introduced for a mechanical rather than a rhetorical purpose. Information Mapping®, a great proponent of unnecessary stem sentences, probably added to the confusion.

In the real world of technical documentation, we cannot assume that the user is reading all the text or reading it in the order we have assumed. If we watch users in usability studies, they skip and scan, move up and down, whether the content is online or on paper. They look for signals, like numbered steps or warning symbols to alert them to “more important” information.

The stem sentence before the steps in a task assumes a reading order that may simply never exist.

See also:

- DITA XML.org poll: What is your opinion of stem sentences?
- DITA-users mailing list thread: Stem sentences

Contributors to this page:

JoAnn T. Hackos, PhD, Comtech Services, Inc.