A Most Sophisticated Error in Technical Writing

While writing plainly with clear terminology is always the goal in technical communication, sometimes we must create a complex sentence (like this one!) to convey our meaning. Or we find that we must include a noun clause (like this one!) or even (shudder!) a modifying phrase or clause.

First, the good news. Complex sentence patterns reveal intelligence and a tendency to write in a sophisticated way. Most experienced technical writers fall into this category.

The bad news is that these sentence patterns are easy to screw up. Let me explain why and provide some tips on how to avoid clouding the meaning of your sentences.

Simple and Complex Sentences

In my previous blog post, “A Call for Plain Language in Medicine: My Story,” I provided some links to plain language resources. The Plain Language movement advocates for writers to use simple sentences whenever possible.

The Word Rake website explains, “Plain language is direct and follows standard sentence patterns, using familiar words.” A best practice is to “Avoid long, complicated sentences. Make sure your writing is clear and concise.”

A more careful definition comes from Peggy McGregor: “Plain language doesn’t mean oversimplifying information. In fact, part of the goal is to help audiences understand your message fully and accurately. So it’s not about making the information itself simple[;] it’s about making the process of understanding simpler.”

Fair, but where do we start with “simpler”? As the Word Rake definition suggests, start with understanding English-language sentence patterns.

Simple Sentence Patterns

According to the Chicago Manual of Style, a simple English-language sentence “consists of a single independent clause with no dependent clause.” An independent clause has one subject (noun) and one verb (S+V). It can stand alone as a sentence, and its meaning is usually straightforward. (The rat jumped.)

Simple Amplified

To up the ante a bit, a simple English-language sentence can also contain an object of the verb (O). (If the verb allows it.) The object can be a single noun, more than one noun joined by a conjunction (a connecting word, usually and or or), or a noun clause. An object answers the question subject+verb what? (The rat ate what?)

Examples of simple sentences:

The rat jumped.  S + V

The rat ate the cheese. S + V + O(single noun)

The rat ate cheese and bread. S + V + O(two nouns)

Simple with Two Twists

Now consider one more example:

The rat said that the cheese was bad.  S + V + O(noun clause)

The words “that the cheese was bad” is a noun clause that also contains a subject and a verb but acts as the object of the sentence’s main verb “said.” Wow! If you think using a clause in place of a one-word noun is tricky, please hold that thought.

Additionally, some English-language verbs can have an indirect object (IO) in addition to the object (O). Both the IO and the O always come after the verb and typically with the IO first.

But sometimes the IO can appear in a prepositional phrase. Prepositions are relational words like to, from, around, and through, which are always followed by some kind of noun or pronoun (me, him, her, you, us, them). (Note that I’ll explain the difference between clauses and phrases later, but you might have already guessed it.)

Examples:

The rat gave me the cheese.  S + V + IO + O

The rat gave the cheese to me.  S + V + O + prepositional phrase with IO

So that’s a neat trick, too. And we’re still talking about simple sentences!

Complex Sentence Patterns

A complex English-language sentence, according to the Chicago Manual of Style, “contains a single independent clause with one or more dependent clauses.”

A dependent clause also contains a subject and a verb, but it always starts with a qualifying word (QW) that connects it to the main part of the sentence. Examples of qualifying words we use to form dependent clauses are because, when, if, while, and after. (The list is long.)

The DC, + IC Pattern

The first sentence in this blog post is a complex sentence because starts with a string of words introduced by the word “while” (While writing plainly with clear terminology is always the goal in technical communication). What follows is the main point of the sentence: “sometimes we must create a complex sentence to convey our meaning.”

The kicker with complex sentences is that both halves contain the basic elements of a simple sentence – a subject (S) and a verb (V).  In the “while” or dependent clause (DC) part of the sentence, “writing plainly” is the subject (a gerund), and “is” is the verb. In the main part of the sentence, “we” is the subject” and “must create” is the verb. The main part of the sentence is called the independent clause (IC). A comma separates the two halves.

Thus the structure looks like this:

(*When the verb is “is,” what follows isn’t technically an object, but I don’t want to complicate things too much.)

The QW + S + V, is the dependent clause or DC. To simplify, the pattern is DC, + IC

Here are some more examples:

While the rat was eating the cheese, the trap closed.   DC, + IC

Because the rat ate slowly, he could not escape.    DC, + IC

When I opened the closet door, I saw him.   DC, + IC

In each case, the complex sentence opens with a qualifying word (QW). They are while, because, and when, respectively.

The IC + DC Pattern

In some English-language sentences, the dependent clause (DC) comes after the independent or main clause (IC). If the two halves appear in that order, a comma is not usually needed to divide them.

Examples:

The rat moved when I poked him.  IC + DC

The door closed as I leaned forward.  IC + DC

I jumped backward because I could hear noises.  IC + DC

In each case, the qualifying word (QW) appears in the middle of the complex sentence. The words are when, as, and because, respectively.

Observations About These Patterns

Four things you should be able to observe about these sentence patterns include two obvious ones and two not-so-obvious ones. Please bear with me – I’m about to explain why what we write can go so wrong.

1. English Sentences Are Additive

Firstly, as I’ve shown, writing an English sentence, even a simple one, can get challenging pretty quickly. One reason is that English sentence patterns are additive. You can add more subjects, verbs, objects, clauses, and phrases by connecting them with conjunctions (and, or, but, etc.). (Remember the example, “The rat ate the cheese and bread.”)

You can also add descriptive words that modify nouns and verbs. These descriptive words, known as adjectives and adverbs, can change the entire meaning of a sentence. That is why they are known categorically as modifiers.

Compare –

I screamed angrily.  S + V with adverb

To –

I screamed joyfully.  S + V with adverb

Single-word modifiers like these answer the questions – How? Which one?

The beauty and frustration of an English language sentence is that we can expand the major pattern pieces with as many add-ons as we want, simply by using conjunctions, qualifying clauses, and modifying words and phrases.

2. Substitutions Are Allowed

Secondly, as with many patterns, we can switch out a simple pattern piece for one that is more complicated but still fulfills the pattern. Remember, the sentence “The rat said that the cheese was bad”? It follows a simple S + V + O pattern; however, in place of a one-word object of the verb “said,” it uses an entire “that” clause as the object of the verb.

Additionally, we can substitute pronouns (I, you, we, us, they, them, she, her, he, him, it) for nouns. Pronouns can be the subject of a sentence and the object of a verb.

Examples:

The rat gave me the cheese. (The pronoun “me” is the indirect object or IO)

I didn’t want it. (The pronoun “I” is the subject of the sentence [S]. The pronoun “it” is the object [O] of the verb “want.”)

3. Order Matters

Thirdly, perhaps a less obvious observation is that despite which sentence pattern we use, the order of the words in the sentence matters. In an active-voice English-language sentence, a subject always precedes a verb. Note that the assumed corollary here is that every subject has at least one verb (and every verb has at least one subject).

Lewis Carroll famously showed the dependence of meaning on positional relationships within the English language sentence through his nonsense poem “The Jabberwocky” in his novel Alice in Wonderland. Even though the poem contains nonsense words, we kind of know what the poem is saying simply because of word order, cue words (prepositions and qualifying words), and punctuation.

Even Yoda from the Star Wars franchise gets his meaning across by following a consistent word order, even if that word order more resembles a pattern of O + V + S than a true English language pattern. (Example: Happy was I.)

Two of the most important word-order rules in English concern modifiers – those added-on pieces of the sentence that modify its meaning:

• A modifier must be placed as close to the part of the sentence it is modifying as possible.
• The word (or phrase) being modified must explicitly appear in the sentence (close to the modifier).

4. Clauses and Phrases Act as Modifiers, Too

Finally, another, less obvious modifier rule presents the biggest monkey wrench so far: clauses and phrases can also act as modifiers.

First some definitions. A clause is a string of words that contains both a subject and a verb (S + V). A phrase is a string of verbs that contains either a noun or a verb, but not both.

• Earlier in this blog post, I introduced prepositional phrases as phrases that start with relational words such as through, from, with, above, around, and under. I used to teach my students that a preposition introduces any relationship you can have with a lake. For example, I can fly over the lake, and I can swim in the lake.
• Earlier, I also introduced dependent clauses as clauses that start with a qualifying word such as because, since, after, and when. Qualifying words introduce word strings—dependent clauses—that provide a sense of context. Dependent clauses often answer the questions–Why? When? or To what extent?

Both types of word strings (prepositional phrases and dependent clauses) act as modifiers in a sentence. They modify the specificity of some part of the sentence or the whole sentence. That is, they slightly alter meaning in some way. (Remember the difference between “angrily” and “joyfully” in the earlier example.)

Here’s the sticky point. Because phrases and clauses act as modifiers in a sentence, they must follow the rules in the third observation above: order matters. (And by extension, clear relationships matter.)

And that, my friends, is where we all get into trouble.  

Modifiers as the Source of the Problem

As a linear, additive language, English permits the stacking of modifiers within a sentence. That license extends to phrases and clauses that act as modifiers. Incorrectly stacking modifying clauses and phrases is the single most common error I have seen as an editor of technical material.

For the following discussion, consider these four sentences:

1. The cat in the tall hat with the big nose hid the cheese.  S (followed by 2 phrases) + V + O.  
2. After I soaked the cheese in the tub of milk, I threw it out. DC (with modifiers) + IC (with pronouns)
3. You can find other related events by using the CLI that could have caused the startup process to fail.  S + V (modified with a phrase) + O (modified with a clause)
4. When trying to access the global message center, if there is no signed certificate, a message will be displayed by the browser that informs the user of the invalid certificate. DC + DC+ IC(passive) + RC

If you read these sentences and were immediately confused, you are justified. Because of modifier problems and other errors, their meaning is ambiguous at best and totally lost at worst.

Word Order as the Problem

The first example sentence above offers some mild ambiguity:

The cat in the tall hat with the big nose hid the cheese.

However, most of us can understand, after a beat, that the cat, not the hat, has a big nose.

The writer stacked two modifying prepositional phrases into the subject part of the sentence. However, the writer breaks the rule that a modifier must appear in the sentence closest to the word it modifies. We are, for a second, unsure whether the propositional phrase “with the big nose” modifies the noun cat (farther away) or the noun hat (closest).

That hesitation comes from the fact that both prepositional phrases, equal in weight, are attempting to modify the same noun – cat. But that’s not how word order works.

A simple fix can clarify who owns the big nose: Rewrite the prepositional phrase “with the big nose” as a hyphenated adjective and place it before the noun cat.

The big-nosed cat in the tall hat hid the cheese. S (followed by one phrase) + V + O

Alternatively, the writer can rewrite the prepositional phrase “in the hat” as an adjective before the noun cat.

The tall-hatted cat with the big nose hid the cheese. S (followed by one phrase) + V + O

However, this version isn’t quite as poetic.

To summarize, to fix this type of problem, ensure that any modifying phrases you add to your sentences clearly modify the word (or phrase) closest to them. If stacking prepositional phrases muddies the meaning of your sentence, edit out one of the stacked phrases.

Pronouns as the Problem

The second example sentence above offers a different kind of ambiguity:

 After I soaked the cheese in the tub of milk, I threw it out. DC (with modifiers), + IC (with pronouns)

The order of the prepositional phrases in the opening dependent clause makes sense. We understand that the cheese is in a tub and that the tub is filled with milk.

The ambiguity occurs in the independent clause—I threw it out. What did I throw out exactly? I could have thrown out the cheese, the tub, or the milk. The reader doesn’t know.

The problem is that the dependent clause introduces many nouns—cheese, tub, and milk. Two of those nouns, tub and milk, occur in prepositional phrases. We know that the pronoun “it” is substituting for one of these nouns; we just don’t know which one.

The solution is to put the mysterious noun back into the independent clause:

After I soaked the cheese in the tub of milk, I threw out the milk.

To summarize, to fix this type of problem, tread lightly when introducing pronouns into a sentence (or set of sentences) that already contains many nouns. Remember that modifying clauses and phrases can include nouns, too. When you use pronouns, ensure that the reader can understand what they are a substitute for. If there is a chance the reader could misunderstand, use the original noun.

Relative Clause as the Problem

The third example sentence above comes from a piece of technical content I edited. The sentence is complicated, but the fix is not.

You can find other related events by using the CLI that could have caused the startup process to fail. S + V (modified with a phrase) + O (modified with a clause)

(Note: CLI refers to the command-level interface)

This sentence is muddied by a prepositional phrase—by using the CLI—that occurs in the middle of the sentence. The writer has misunderstood what the phrase is modifying. It appears to modify the verb “find.” But, in fact, the phrase modifies the whole sentence, so it should be moved to a more appropriate spot.

Additionally, the writer fails to understand the word order rule about modifying clauses: they must be close to the word or words they modify. The clause—that could have caused the startup process to fail—modifies the word “events.” But the clause is too far from the word it modifies for the sentence to make sense.

The fix is to reorder the sentence:

By using the CLI, you can find other related events that could have caused the startup process to fail.

If words like “using” (a gerund) don’t work for your style standards or translation services, you can recast that part of the sentence as a dependent clause.

When you use the CLI, you can find other related events that could have caused the startup to fail.

Or more directly—

If a system startup fails, use CLI commands to evaluate any related system events.

Note the modifying clause at the end of the first two rewrites starts with a “that.” The word “that” signals that what follows is a relative clause. Relative clauses (RC) start with that, who, whom, whose, and which and always contain a verb and sometimes a noun. They act as modifiers that typically answer the questions—Which one? or What kind?

Here are some additional examples of sentences with relative clauses:

The boy who never napped grew up to be a sleep specialist.

They gave him the sense that things would go smoothly.

The author, whose latest novel was a best-seller, stood alone in the hallway.

I forgot my briefcase, which I had left under the desk.

Relative clauses demand conscious placement in the sentence order. If they do not fall immediately after the word they are modifying, ambiguity and misunderstanding can ensue. Use them very carefully.

On a final note, sometimes a relative clause is superfluous to the meaning of the sentence, but including it adds rhythm, drama, or some additional effect. That is true about the sentences about the author and the briefcase (above). In each case, the relative clause could be taken out and written as a separate sentence:

The author stood alone in the hallway. His latest novel was a best-seller.

I forgot my briefcase. I had left it under the desk.

But in both situations, the rewrite lacks the original’s impact. Combining short sentences by turning one into a relative clause can certainly help you avoid choppiness in your writing. Just tread carefully.

Passive Voice as the Problem

In the final example sentence above, I offer up another common problem in technical communication—passive voice. This sentence, which I encountered as a technical editor, is so tangled with modifiers and the action so buried, that the reader struggles to follow along:

When trying to access the global message center, if there is no signed certificate, a message will be displayed by the browser that informs the user of the invalid certificate.
DC + DC+ IC(passive) + RC

At the center of the problems with this sentence is the buried action—a message will be displayed by the browser. Did you find it on the first read? Probably not since the idea of a “user” is buried in a relative clause—a “that” clause (that informs the user of the invalid certificate).

Once you understand the user will see a message, you can begin to understand that certain conditions—dependencies—must exist for this action to happen:

• Someone or something is trying to access the global message center
• A signed certificate is missing

One of the many problems with this sentence is that despite its length, it lacks specificity. “When trying to access…” is a dependent clause that is missing its subject. Who or what is trying to access the message center? I assume it is the user. What kind of signed certificate is missing? I assume it is some sort of system-level security certificate that grants access.  

So, in my first rewrite (re-right) of this sentence, I go with my assumptions. I flip the action into active voice and put the modifiers in their most meaningful order:

If you try to access the global message center and do not have the proper security, your browser will display an “Invalid Certificate” message.

 (By the way, I disagree with Grammarly’s attempt to rewrite this sentence, but that is a story for another day.)

But of course, I couldn’t be sure that my assumptions were correct. So, I had to send the author back to her subject matter expert for clarification and detail. Turns out the intended audience for this sentence is a data storage system administrator who is setting up system security, and the global message center is where the browser message originates (and thus isn’t important). Here is the final version of the sentence:

If no SSL certificate is present in the system when a user logs in, the user’s browser will display an “Invalid Certificate” message.  

My final advice for writing sentences that include modifiers, therefore, is to always check that the detail you include is exactly—and only—what the intended audience needs. Meeting the needs of the audience is the first and last rule of good communication—and of communicating in plain language. “Plain language will increase trust, loyalty, and show [your customers] that your company cares about them,” says Deborah S. Bosley, Ph.D., founder of The Plain Language Group. That’s as good a goal as anyone can strive for.

If you have more examples that you want to share, please add them in the comments section. If you want to know more about any of the concepts I have discussed here, please contact me at debra@dkconsultingcolorado.com.

Featured photo by Kelly Sikkema for Unsplash.