Odile Sullivan-Tarazi

View Original

A look at one well-organized technical paragraph

Careful, cohesive writing carries us smoothly through the material

When a piece of writing leads us smoothly through its topics, we say it flows well. Each sentence prepares us in some way for the next. Each seems to follow naturally, perhaps almost inevitably, one from the other. We always feel well located in the discussion. We know where we’re going, very clearly, in the moment; and at the same time we are engaged in putting together the bigger picture. We are building in our minds the model of the information — concepts, process, argument, whatever — conveyed by the words. For we must disassemble and then reassemble, transfer from page to mind, in order to comprehend.

In such text, any surprises we encounter have most often to do with the information being conveyed — with substance, that is — not with the manner of writing. The writing is a steady and capable guide. When the information is rich and complex, we may have to work to fully grasp the material. But the work we do is focused on mastering the concepts, not on getting through the writing.

Such writing, writing that flows well, that’s smooth, we say is cohesive. When it is also logically organized, when it doesn’t stray or ramble from the point, when there’s a kind of internal map, we say that it is coherent. In reality, the two concepts are as inextricably linked as the terms themselves. Something that is cohesive also (in its active, verb form) coheres. Something that coheres is (in its descriptive, adjectival form) coherent. But most writing guides will focus on cohesion as the relationship of one sentence to the next and on coherence either as the relationship of each sentence to the larger whole or as the way in which all those sentences, taken together, create that larger whole.

This cohesion-coherence dyad is a powerful tool for writing in a way that readers can easily follow. And you can see it at work in this paragraph —

The passage is not lyrical and lovely (nor is it meant to be), but it is clear and tight. It carries us along — even if we are completely new to these concepts — in text that is easily comprehended, easily absorbed. Yes, each reader brings his or her background to it, and those who are new to the concepts will find more to unpack in the material than those who are not. But the text assists with that process: the writing helps to guide comprehension, rather than impede it.

And that’s because the writer has made use of several strategies for cohesion and, ultimately, coherence.

The known-new contract

A standard strategy for writing clear, readily comprehended expository text is to write from what the reader can be presumed to know (or what you have just introduced) to what is new, to the point this current sentence wants to convey. To write to this strategy, you begin sentences — not absolutely every sentence, but many of them — with the known information and end on the new.

It means leading into the new information, placing it to the right, typically following the verb. And that, in turn, offers two benefits: you’ve more space to develop the information at greater length, and that information is placed also in the position of natural emphasis in a typical English sentence. (For more on the end focus of English, see One perfect sentence.) Across sentences, there’s a third benefit. Writing this way also helps to link the sentences together in a kind of chain: each sentence opens with the known information that ties that sentence back to the preceding text, and each ends on the new, providing you a link then into the next sentence.

This strategy is sometimes referred to as the known-new contract, and writing to it means recognizing something about reader comprehension and something about the structure of English sentences. Writing to this style is only one strategy among many, but it is a significant one for any writing designed to guide the reader through concepts or processes, any writing designed to teach, any writing designed to explain. So it is a strategy very much in evidence in technical writing.

Take a read through that paragraph again.

If you’re watching for it, you should now see how the information towards the ends of several sentences (or in one case, of the main clause) is information that is both newly introduced in this sentence and preparatory for the next sentence (or sometimes, sentences). It is the culmination of one thought, and the springboard into the next.

That strategy is particularly noticeable at the beginning and the end of the paragraph (color here added to highlight the linking of info) —

When you read through the passage the first time, this linking of known to new, to known to new, to known to new helped carry you along through the material, likely without you even realizing it. The structure sets up an easy pace, rendering concepts more digestible.

But it’s not the only strategy at work. In the middle of the paragraph, other strategies for connecting with the reader are in evidence.

Metadiscourse

Metadiscourse is writing about writing. Metadiscourse provides signposts for the reader that help to structure the material. Those signposts may signal something about your own intent or perspective (with phrases like turning now to, clearly, or unfortunately). They may directly invoke reader participation (with phrases like note that or as you may recall). Or they may clarify the purpose or direction of the discussion (with phrases like consequently, for example, on the one hand, or by contrast). Such phrases help to provide cohesion and also, in signaling larger structure, coherence.

In this paragraph, the numerical terms first and second signal textual structure and so count as metadiscourse, but they also tie back to an earlier phrase (at least one of two conditions) in the manner of known to new —

The first and second points that follow then follow directly from that mention. We are prepared for the catalogue.

This bit of metadiscourse layers a different sort of structural support, a different sort of linking of thought, into the paragraph.

Parallel structure

When you present like ideas in like structures — within or across sentences — that’s using parallel structure. Structuring thoughts to be taken and weighed together in parallel helps with clarity and comprehension. It helps with the coordination of longer structures. And it can help also with cohesion across a passage.

In this paragraph, parallelism is most overtly at work in two sets of sentences —

The metadiscourse of enumeration sets up an opportunity here for parallelism, in the middle and then at the end of the paragraph. In the first case, for two conditions. In the second, for two different OS components. The parallel positioning of these two, and the parallel phrasing, provide the scaffolding for us to more easily take this information in.

Subjects and predicates

In terms of the structure of sentences, the most basic framework is simply subjects and predicates.

Refocusing the lens more widely to look in this paragraph simply at subjects and predicates, you’ll see this —

Short subject phrases, primarily naming the same themes. Verbs quickly arrived at, naming interrelated or repeat actions. And a kind of overarching parallel structure to the paragraph as a whole, in the way that sentence cores mirror one another.

Note that passive voice (so often denigrated) is used here to good effect, both to highlight what in the sentence is important and to assist with cohesion, and of course, never when the agent of the action would be left in doubt. The passive structure of the sentence that’s third from last in this paragraph, for example, (this one: The scope of access is controlled . . .) enables the names of the two managers to appear at the end of the sentence. And that, in turn, means both the best position in this sentence for the new information and a tighter cohesive link with the information in the next two sentences.

This is one of the passive structure’s great gifts: another strategy for cohesion.

Semantically cohesive ties

So far we have looked at structural strategies for cohesion. The known-new structure of exposition sets up a chain that extends across sentences. Metadiscourse layers signposts on top of that structure, often of presentation or intent. Parallel structure helps us to locate similarities, and in that way also highlights the most important differences. Even the most fundamental structure of all, subjects and predicates, can be used in a way to help ground readers in the material.

Techniques that have to do with the structure of the sentence are techniques of syntax. The syntax of a sentence is simply the structure of that sentence. But cohesion is also achieved semantically, that is, through meaning.

In this paragraph, for example, there’s the concept of memory, access to memory, and the granting of that access —

And then, towards the end of that progression, the reader learns that the access to be granted has scope.

This idea of scope is inherently related to the other primary set of concepts layered into the paragraph, that of software components being “trusted.” Where trust is an issue, defining a scope (or range) for that access is not out of place. Even though the concept has not been explicitly introduced, it does not jar. Note too that the term component, one of key players in the passage, also repeats throughout.

In literary writing, writers are cautioned against using the same words too often, unless, of course, such repetition is deliberate and has been designed to good effect. But in expository writing, particularly when it is also heavily technical — in whatever field, so the principle is widely applicable — using the same words rather than synonyms is a way of anchoring the text for the reader, a way of providing stepping stones through the material. In technical writing, repetition is your friend.

In this paragraph, into this constellation of memory and trust and access and the scope of that access — and the skipping through of component — come now two new players, players with significant roles in this whole process —

The names of these components, the fact that they are managers, accords with the concepts of access requested and access granted.

The verbs used throughout the paragraph are also cohesive: in the process of being provided, access is requested and granted, and during (or perhaps as a result of) this process, it is also limited, controlled, and overseen — 

The concept of a digital signature “with the proper rights” is related as well to the intertwined concepts of trust and access and scope. There is scarcely a word in that paragraph not picking up and interleaving related ideas in one way or another. 

As good, tight expository writing so often does. Every word is doing work. No words are wasted.

. . .

The end result of this attention to cohesion is a paragraph that is quickly scanned, easily grasped. Even if we come completely fresh to this material, even when many of the concepts within it are foreign to us, we get the gist. Structure and semantics work together to usher us through the ideas — as should they always.

From a lecture-discussion in a course on rhetorical grammar,
taught at UCSC Extension in the late ’90s through to 2001