KYSSURWAV: Tips for Better Technical Writing

KYSSURWAV: Tips for Better Technical Writing

Print Article

Taller, shorter. Larger, smaller.

Brighter, dimmer.

Louder, quieter.

Heavier, lighter.

Faster, slower.

These words are “comparatives.” They compare qualities, characteristics, and properties. For some reason, comparative words are often overlooked in favor of two simple, drab words:  “more” and “less.”

For example, I read this sign at an amusement park: “Children less than 4’ may not ride.” Technically, children less than 4’ is accurate, as long as we know you’re talking about height and not children less than 4’ in any direction. Children less than 4’ isn’t even ungrammatical. But there’s more to good writing than accuracy and grammar. There’s style.

Writing style refers to word choice and sentence structure, as well as to how paragraphs are put together and how documents are sequenced, all of which optimizes meaning. It’s better writing to say “a child must be 4’ tall to ride” because “tall” describes what we want the child to be. Using all-purpose words such as “less” and “more” is stylistically weak, because it leaves us wondering “less” or “more” what?

While other aspects of writing (grammar, punctuation, etc.), are rule-governed, standardized, and predictable, style is somewhat subjective. I know that’s the sort of thing that sends engineers running in the other direction because it seems fuzzy and murky, like art, rather than straightforward and reliable, like math.

Fear not. I’m going to help you improve your writing style without getting too nebulous. I’ll make this prescriptive and objective.

Use the Right Word

Don’t Settle for “More” and “Less”

So that’s one easy-to-implement idea: when you’re measuring and comparing this to that, use the word that describes what you’re actually comparing. If you’re comparing height, use taller/shorter. If you’re comparing size or volume, use larger/smaller. Don’t just settle for less and more.

Throughput is more than 2 Mbps. (Bad.)

Throughput is faster than 2 Mbps. (Better.)

An aircraft has more weight at take-off than landing. (Bad.)

An aircraft is heavier at take-off than landing. (Better.)

The innovative design produced a lamp with brightness that was less than expected. (Bad.)

The innovative design produced a lamp that was dimmer than expected. (Better.)

Use Words That Describe Action!

Most technical writing suffers from a serious case of the blahs. One reason it’s a yawner is that the writing lacks lively verbs. It has verbs, of course–such as is, have, make, etc.–but those verbs, while useful, are so ho-hum. Instead, use verbs that engage a reader’s ability to picture something, words like assess, oversee, instruct, observe, predict, confirm, assert, assent, certify, foster, eradicate, immolate, bolster … I could go on. Technical and business writing takes those clear and memorable verbs and shoves them into a them into the language chipper shredder. They come out the other end a pile of word rubble, rendered into plodding nouns, nudged along by boring verbs (is, has, do, etc.). So assess becomes assessment. Delay becomes postponement. Discuss becomes discussion.

And this matters because …?

Sentences with boring verbs and clunky nouns instead of lively verbs are wordier, more convoluted, and they lack movement. Example:

The team conducted an assessment of network performance and then engaged in a discussion about whether the performance was satisfactory.

Now, once again, with verbs:

The team assessed network performance and then discussed whether the performance was satisfactory.

Savings: seven words — 35%! Not only shorter, but neater. Better style.

Clunky nouns need boring verbs. Here are a few more examples (notice boring verbs in bold, better verbs are underscored):

We made an observation of the situation. (Bad.)We observed the situation. (Better.)

No one provided confirmation that the product arrived on schedule. (Bad.)

No one confirmed that the product arrived on schedule. (Better.)

There was an expectation by the team that the test would fail. (Bad.)

The team expected the test would fail. (Better.)

Observe, confirm, and expect are perfectly good verbs. Don’t fall into the habit of stripping them of their action and mutating them into nouns, then padding them with weak verbs (is, has, do, etc.).

Just let verbs be verbs, and your writing will be punchier and more efficient.

Keep Your Sentences Short

Every sentence in English must have two things in order to be a sentence: a subject and a verb. Without both, it’s not a sentence. It can have other things (adjectives, prepositions, etc.) but it must have those two.

The project ended. That’s a sentence. Project is the subject; ended is the verb.

The project ended on time, thanks to the conscientious participation of the entire team, a helpful financial analyst, a responsive vendor, responsible leadership, and a bit of luck when we needed it most. That’s also a sentence. But at its essence, it says “the project ended.”

Writing long sentences is never necessary. Know the essence–that is, the subject/verb–of every sentence you write, and avoid trying to say a lot more.  Academics do so, I guess to prove they can. But no one else thinks it’s a good idea. If your college professors encouraged you to elongate your sentences, give up the practice.

The truth is that readers don’t want to read them, and most people don’t write well enough to write readable long sentences. Keep your sentences short.

Active Voice

A decision has been made to cancel the second phase of the project. This will be communicated to all contractors, and termination dates for each contractor will be determined. Notification will be made to all parties involved.

I don’t know about you, but I always hate reading things like that. “A decision has been made….” Who made it? “Dates will be determined….” Who will determine them? “Notification will be made…” Who will tell what to whom?

The style shortcoming in these few sentences is that they lack actors. No one is identified as the decider, communicator, determiner, or notifier, and it’s frustrating for readers not to know who did it, especially if the news is unwelcome or controversial. It sounds like bureaucracy, and that’s exactly where this awful style of business writing was perfected: by bureaucrats who were hiding themselves and their deeds (and misdeeds).

The stylistic term for this sort of awful writing is called “passive voice.” The opposite, which is far better, is “active voice.” There’s no mistaking in active voice who the perpetrator is of any and all deeds.

The Customer Service management team has decided to cancel the second phase of the project. Project team leads will communicate this to all contractors, and will determine the termination dates for each contractor. Project Manager Rob Gray will notify all parties involved, including vendors, Finance, Network, and Ops.

Passive voice is wussy writing. The only time it’s excusable (in my opinion) is when we don’t know who did it or it’s really, genuinely irrelevant and uninteresting. Otherwise, put the actor in the sentence. It’s better writing.

“We Buy Your Car”

Have you seen the commercial for CarMax where the customer tells the sales guy that he wants to sell his car to CarMax but does not want to buy one? The salesman cheerfully replies “WBYCEIYDBO!” (pronounced we-be-ce-DEE-boh) and then explains that this is an acronym that stands for “We’ll buy your car even if you don’t buy ours.”

If CarMax can create a silly acronym for their customers, so can I. To help you remember these essential writing improvements, here’s your acronym: KYSSURWAV, pronounced “kiss your wave.” It stands for Keep Your Sentences Short, Use the Right Word and Active Voice. I hope this phrase catches on in the hallways where you work.

KYSSURWAV!


Susan de la Vergne is a writer and communication instructor who worked in software development and Information Technology leadership for a very long time. Susan is the author of Engineers on Stage: Presentation Skills for Technical Professionals. Find more of her Cogent Communicator columns here.


Leave a Reply