WRITING

Parts of Speech

Part of SpeechDefinitionExample
Nounperson, place, concept, or thingLiam plants flowers
Pronounnoun that replaces another nounLiam plants flowers. He likes the way they smell
Adjectiveword or phrase that modifies a nounEmerson wears red shirts
Verbaction word or phraseLiam plants flowers
Adverbword or phrase that modifies a verb, adjective, or other adverbLiam plants quickly
Prepositionword or phrase specifying the positional relationship of two nounsEmerson’s shirts are rarely in his closet
Conjunctionword that connects two nouns or phrasesGavin’s trophies and ribons are on the shelf
Transitionword or phrase that connects two sentencesGavin likes red. However, blue is his favorite

Words

Repeatability

In technical writing, use the same word repeatedly when referring to the same idea.

In prose, mix it up with synonyms to make it sound less mechanical

Acronyms

The first time you use an unfamiliar acronym, spell out the full term and put the acronym in parentheses.

In technical writing, put the entire thing in boldface

Disambiguate pronouns

Since pronouns often point to a previously introduced noun,

It and they

it , they, them, and their cause the most confusion. For example, what does It refer to here:

Roses are red, violets are blue. It smells really nice

What does their refer to here?

Be careful when using epoxy or glue with wood or metal because a impurities in their composition may cause a failure

This and that

this and that also present problems. For example, in the following sentence This could refer to clamping pressure, to the locating, or both.

Assembling the screws locates the parts and applies a clamping pressure. This makes the assembly ready for testing..

Active vs Passive Voice

The active voice is usually more direct and vigorous than the passive. The vast majority of writing should use the active voice. Most readers mentally process passive to active anyway, so writing in passive incurs and additional mental load.

An active voice sentence follows the form: actor + verb + target. For example:

I shall always remember my first visit to Boston.

A passive voice sentence follows the form: target + verb + actor. For example:

My first visit to Boston will always be remembered by me.

Recognizing passive verbs

Passive verbs typically follow the form: form of be+past participle verb, where:

form of be is a passive verb. Usually is/are or was/were

past participle verb is typically a plain verb plus the suffix ed (e.g. tested, generated). Some past participle verbs are irregular (e.g. sat, known, frozen).

Putting some of those words together yields passive verbs:

Imperative verbs are usually active

An imperative verb is a command, but it can at first blush seeem to be passive. Many items in numbered lists start with imperative verbs. For example, both Open and Set in the following list are imperative verbs.

  1. Open the door
  2. Disable the alarm

Thoreau: Active vs Passive

From William Zinsser

I went to the woods because I wished to live deliberately, to front only the essential facts of nature, and see if I could not learn what it had to teach, and not, when I came to die, discover that I had not lived.

vs.

A decision was made to go to the woods because of a desire for a deliberate existence and for exposure to only the essential facts of life, and for possible instruction in its educational elements, and because of a concern that at the time of my death the absence of a meaningful prior experience would be apprehended.

When Passive Voice is Good

example from Strunk and White

Sometimes passive voice is useful. Consider the following active and passive sentences.

The dramatists of the Restoration are little esteemed today.

Modern readers have little esteem for the dramatsits of the Restoration

The first would be the preferred form in a paragraph on the dramastsists of the Restoration, the second in a paragraph on the tastes of modern readers.

Clear Sentences

Choose strong verbs

Pick the right verb and the rest of the sentence will take care of itself. Strong specific verbs preferred, so avoid weak verbs like:

Consider the difference in the following sentences:

Weak VerbStrong Verb
The error occurs when clicking the Submit buttonClicking the Submit button triggers the error.
This error message happens when…The system generates this error message when…
We are very careful to ensure…We carefully ensure…

Note that generic verbs often signal other ailments, such as:

Reduce There is/there are

Sentences that start with There is or There are marry a generic noun to a generic very, and it’s boring. When people are bored they don’t read. Consider the following:

There is a guy named Hank that knows about taxes.

Removing **There is ** replaces the generic subject with a better subject. Fro example, either of the following sentences is clearer than the original:

A guy named Hank knows about taxes

Hank is a guy that knows about taxes.

You can sometimes repair a There is or There are sentence by moving the true subject and true verb from the end of the sentence to the beginning. For example, notice that the pronoun you appears towards the end of the following sentence:

There are two disturbing facts about Thomas you should know.

Replacing There are with You strengthens the sentence:

You should know two disturbing facts about Thomas.

In other situations, writers start sentences with There is or There are to avoid the hassle of creating true subjects or verbs. If no subject exists, consider creating one. For example, the following There is sentence does not identify the receiving entity:

There is no guarantee that the dimensions will be identical.

Replacing “There is” with a meaningful subject (such as parts) creates a clearer experience for the reader:

Parts might not have identical dimensions.

Adjectives

Good for grabbing attention.

Setting this flag makes the application run screamingly fast.

But screamingly is too loosely defined for techincal writing. Better to do something like

Setting this flag makes the application run 225-250% faster.

Short Sentences

Shorter is easier to read, easier to edit, easier to maintian. Try to write short sentences.

Focus each sentence on a single idea

Consider this sentence that contains multiple thoughts.

The late 1950s was a key era for programming languages because IBM introduced Fortran in 1957 and John McCarthy introduced Lisp the following year, which gave programmers both an iterative way of solving problems and a recursive way.

Breaking it into several sentences yields:

The late 1950s was a key era for programming languages. IBM introduced Fortran in 1957. John McCarthy invented Lisp the following year. Consequently, by the late 1950s, programmers could solve problems iteratively or recursively.

Convert some long sentences to lists

Inside many long technical sentences is a list yearning to break free. For example, consider the following sentence:

To alter the usual flow of a loop, you may use either a break statement (which hops you out of the current loop) or a continue statement (which skips past the remainder of the current iteration of the current loop).

Breaking it into a list yields:

To alter the usual flow of a loop, call one of the following statements:

  • break, which hops you out of the current loop.
  • continue, which skips past the remainder of the current iteration of the current loop.

Using lists too much can yield an outline that no one wants to read, but discerning usage can make list-like content more easily digestible.

Eliminate or reduce extraneous words

If it is possible to cut out a word, always cut it out. – George Orwell

Many sentences contain filler—textual junk food that consumes space without nourishing the reader. For example, see if you can spot the unnecessary words in the following sentence:

An input value greater than 100 causes the triggering of logging.

Replacing causes the triggering of with the much shorter verb triggers yields a shorter sentence:

An input value greater than 100 triggers logging.

Bad words and clichés

Think twice before using these words. Clichés numb rather than stimulate te brain

Style guide tools

Negative reactions to writing

From the Ecoomist course on writing

Wandering

It’s not clear why one paragraph follows the next. The author may have written many disparate things, all of which may be relevant to the topic under discussion, but seems not to have arranged them so that each follows on from, or builds upon, what went before. Or you get the impression the author hasn’t worked out what precisely the piece is supposed to “do”—to describe something? To make an argument?—but is merely writing “about” something with no clear purpose.

Choppy or disjointed

The argument or narrative has unexplained gaps. It may consist of assertions without evidence—or, worse, be a series of assertions that the author claims follow on from one another, when in fact they don’t.

Contradictory

The author seems to be arguing opposite things at different times. There are several possibilities here. One is that the topic is controversial and the author is reluctant to say what she or he really thinks. Or the author can genuinely see both sides of an argument, and wants to be fair to both, but hasn’t explained at the beginning of the piece of writing that the plan is to explore pros and cons. Or the author may be sure which side of an argument to take, but wants to state caveats and counter-arguments before dismissing or disproving them. If the author hasn’t signalled that this is the plan, the reader may be left confused.

Dizzying

The author keeps arguing from different positions or points of view, or repeatedly switches from facing one way to the other and back again. The reader feels like an umpire at a tennis match. This can happen with writing that is supposed to compare and contrast two options or ideas, unless they are deftly handled.

Vague

The words are bland and high-level, and it feels like there is nothing to hold onto. This happens when a piece is about an abstract or complex idea or concept, and the writer has neglected to give examples or use comparisons. A well-chosen metaphor might have made all the difference.

Boring

This will often be your reaction when the writer is covering something very familiar to you, or gives too much detail—or indeed is writing about a topic that goes right over your head. The first thing to decide is whether you are, in fact, the intended audience. Has the author done a great job of writing for people who know much more or much less than you do? Or have they droned on, with long explanatory passages but no clear idea of what is being explained or why? Alternatively, have they left out the details needed to convey their message and the evidence needed to back up their claims?

Pointless

This may be because it’s clear what the author is saying, but not why. The author has either not settled on a message before starting to write, or failed to convey it. Or it may be a perfectly fine piece of writing, but you simply are not interested. If you find yourself saying “so what?” after reading something, consider whether other people would, in fact, be riveted (one person is left cold by changes to the rules of cricket; another by the details of medieval fabric-making).

Research

References