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

SDI

jvazquez@sdicorp.com

919-354-1123

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 

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>

<step>...</step></steps>

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
Scripto
Belgium