Stem sentences

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 poll: What is your opinion of stem sentences?
- DITA-users mailing list thread: Stem sentences

Contributors to this topic:

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

Lots of interesting points here. Some of the stylistic concerns have been around for a while and even recently I was engaged in a discussion about stem sentences and how a style guideline required them. While following guidelines ensures consistency those same guidelines may become a stumbling block when putting together your information.

Back in DITA 0 the task topic was devoid of any heading construct so that even though you had the correct semantics there were no visual clues as to what was prereq, context, and the rest. This made folks scream about the structure and the need for stem sentences and some other visual way to identify the different semantical elements. That's when some intelligent folks started using XSLT to override the output processing to produce tasks that gave the readers the visual clues they needed. Done correctly you can eliminate the need for stem sentences altogether because your reader will see headings such as "Before you begin," "When and why to use this task," and "Procedure."

Are stem sentences necessary? With task-oriented topic titles and enough clues for the rest of the content I think not.

Julio J. Vazquez



The poll attached with this article assumes an either or positon. It does not provide a middle ground option which is mine. I understand the minimalist approach to not using stem sentences, but also feel Jim Owens makes a reasonable argument for the use of stem sentences.

Unless the poll is altered to accomodate this middle ground, it will fail to have any meaningful results. There are clearly shades of gray to this issue.

Rob Frankland

Sock Monkey Consulitng 

I wholeheartedly agree with robf.  I sometimes use stem sentences and sometimes don't.  It all depends on what is appropriate for my target audience.  There are most definately grey areas in this debate; my feeling is that if you say they are "unnecessary under any circumstances" then the target audience is not being considered at all. 


Dee Vincent-Day
Technical Author


We should weigh the costs and benefits of adding a stem sentence structure to DITA.

The immediate cost is to define a new element, and to permit it in one other element as an option. This cost is so low that almost any benefit would outweigh it.

The immediate benefit is to accommodate documents that use stem sentences. Given the high incidence of stem sentences in legacy documentation, and the widespread use of stem sentences even today, this is a significant benefit that can make DITA more expressive and increase its user base.

On the basis of these costs and benefits alone, there can be no doubt: we should add stem sentence support to DITA.

Resistance to the proposal seems to be based on another perceived cost: the violation of minimalist writing principles. According to these principles, stem sentences are extra words; extra words make documentation more dificult to use; therefore, stem sentences make documentation more difficult to use. But the resistance goes further, asserting implicitly that DITA is, or should be, a tool to enforce minimalist principles.

These assumptions are contentious. Some DITA users agree that they are valid, and some disagree. In light of the clear costs and benefits already discussed, these assertions should be discounted as in dispute.

However, we can examine them.

DITA is first and foremost a tool for creating single-source documentation. To the extent that it uses structures, it is a tool for enforcing structured writing. To the extent that its structures allow or disallow certain forms of expression, it is a tool for guiding expression; but this is at best a tertiary purpose. For the most part, DITA is flexible enough to allow many forms, and on the question of verbosity it is agnostic. This is as it should be. A DTD has no place dictating minimalist writing principles. One that assumes this role runs the risk of losing its true focus and its real audience. We need to make DITA the best single-sourcing solution available. It does not also need to be the Style Police .

Minimalism has its adherents, not only in technical writing, but in music, architecture, industrial design, business management, and other forms of human endeavour. But not everyone who composes music or designs buildings or bicycles is a minimalist, and this too is as it should be. Minimalism can produce unsatisfactory results: music that is boring, buildings that are unpleasant, bicycles that jar the body, and in the case of writing, material that reads awkwardly. This is not necessarily to reject minimalism. It is only to plead for the freedom to choose minimalism for its perceived advantages, or to reject it for its perceived weaknesses, and to let the market decide which produces the better result.

Minimalism is a fashion. The current wisdom that stem sentences make documentatiion harder to use has replaced the previous wisdom of Information Mapping, which encouraged the use of stem sentences. What will we believe ten years from now, when (as we hope) everyone is using DITA?

In the minimalist argument against stem sentences, there is something of the begged question. Extra words make documentation harder to use; stem sentences are extra words; therefore stem sentences make documentation harder to use. Having reached this conclusion based on precepts, we are blinded to whether stem sentences actually do make documentation harder to use. To be sure, users "skip and scan" and "look for signals", but the truth is that stem sentences are signals. Jumping out of the grey blob, they say, "Here is where the instructions start." Simply seeing a numbered list is not enough. Does the numbered list contain prerequisite considerations? Does it enumerate different things you can do? Numbered lists can be used for things other than instruction steps, and so their meaning in a grey blob can be ambiguous. Stem sentences instantly and elegantly dissolve any ambiguity. Therefore, at least in some cases, they are useful. In fact,they can make documentation easier to use.

Stem sentences have their drawbacks. The point that they are sometimes blatantly redundant is well-taken. Another problem is that they characteristically end with a colon, which then shows up in cross-references, as in "See "To open the can:". But some people argue that they do have legitimate uses. To those people, we can say, "Well, yes, but you could do that another way." But that is not the point. If you can meet a need effectively with a stem sentence, why should you have to do it another way?

It's an entertaining discussion, but let's not lose focus: DITA is about providing a brilliant single-sourcing solution. In this context, the merit of stem sentences is beside the point. With a few dozen keystrokes, we could add them to the DTD as an option. Why not just do it, and leave people to make their own decisions on this controversial issue? 

Great article,

as a former Information Mapping instructor, I used to promote using stem sentences, but since I started using DITA I agree that there is no use for them anymore, particularly not if you're applying the principles of minimalism correctly. So I've changed our company style guide to get rid of them. The titles will function as stem sentences to introduce the task. And even if you are still using Information Mapping, you can avoid stem sentences. For example:

<maptitle>Rotating Objects</maptitle>

<blocklabel>About rotating objects</blocklabel>

<blocklabel>To rotate objects</blocklabel>

<steps><step>Select the object.</step>



I'd doubt whether "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)". Well, it may be the case for Word, but not for FrameMaker ;-), because FrameMaker in itself does not have any problems with numbering. You can easily restart the numbering of your steps, simply by introducing a new title (or a "block label" in Information Mapping). The chunking principle implies that you can have only one task (procedure) in each block (or topic). Sometimes, however, users do want to have two (alternative) procedures in one block, and then a stem sentence which restarts the numbering may come in handy.

I'd definitely not put a stem sentence in the <context> element, because that would be "tag abuse".



Yves Barbion
Belgium 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