by J. M. Haile

Metawriting, a.k.a. metadiscourse, is writing about writing. This essay is one kind of metawriting, but it is not the kind we discuss here. Instead, we discuss use of metawriting in technical documents. Such metawriting divides into two classes: large forms and small forms.

Large-Form Metadiscourse

Large forms of metadiscourse include introductions and summaries. In technical documents, the introduction is intended to help the reader understand how the document is organized and how its parts are related. The development can be guided by titles of chapters and headings of sections. In an introduction, emphasis should be on the document not on the message, though a well-written introduction should show how the document's structure reinforces development of the message. Readers should leave the introduction with a sense of how the document is divided into parts and what is contained in the principal parts. The writer's challenge is to do this briefly, so that readers do not become mired in unnecessary details.

While an introduction emphasizes the document, a summary emphasizes the message conveyed by the document. Two kinds of summaries are in common use: executive summaries, which precede the body of the document, and concluding summaries, which follow the body. Both contain a synopsis of the message and the principal evidence that supports that message. The test for a good summary is that it should be able to stand alone, separate from the rest of the document. Writers should aim for brief summaries, but completeness is more important than brevity. Long complex documents generally require long summaries.

Introductions and summaries are difficult to write, and it is not unusual to work through several drafts of each. Some writers draft them before drafting the body; others draft them after drafting the body. Both approaches can be used to advantage. For example, in some cases, you might use the introduction as an outline to help guide the writing of the document, but in other cases, you might use the body to guide the writing of the introduction.

Small-Form Metadiscourse

Small forms of metadiscourse include phrases, sentences, and checkpoints. Small-form metadiscourse usually appears as a phrase or single sentence that links parts of a document and helps keep the reader "on message". These links are signposts that guide readers and keep them from becoming lost or overwhelmed. Here are some examples:

  1. In Section 3.2 we stated the relation between A and B; that relation is proved here.
  2. In Equation (4.2) we showed that ...
  3. This effect is illustrated in Figure2.5.
  4. The data are presented in Appendix B.

Note that these examples are not about the message, but about the document—about the way the document is organized to present relevant information.

When we develop long or complex arguments, it is helpful to occasionally interrupt the presentation with a paragraph of metadiscourse that we call a checkpoint. In the checkpoint we (a) remind the reader of our objective, (b) review what has already been done toward that objective, and (c) state what will be done next. A checkpoint is never more than a single paragraph; often, it appears as the first paragraph in a subsection.

Nonlinearity and the Goldilocks Effect

Novels are written to be read linearly: the reader is expected to start on page one and proceed sequentially to the end. Of course, the novelist may develop the story nonlinearly using such devices as flashbacks, foreshadowing, and alternative points of view; nevertheless, the reader is expected to follow the development linearly.

But technical documents are not necessarily read linearly, nor are their arguments necessarily developed in a linear fashion. Metadiscourse helps readers remain oriented so they do not become victims of a nonlinear development. A short technical document that develops its message linearly requires little, if any, metadiscourse. Much more must be used in a long document that develops a complex argument in a highly nonlinear way.

The challenge is to achieve the right amount of metadiscourse. Too much becomes distracting and can aggravate readers; too little may leave readers disoriented and confused. Thus, metadiscourse exhibits the Goldilocks effect: the amount must be neither too much nor too little, but just right.