Ramblings on Technical Writing

The secret of good writing is to strip every sentence to its cleanest components. Every word that serves no functions, every long word that could be a short word, every adverb that carries the same meaning that's already in the verb, every passive construction that leaves the reader unsure of who is doing what - these are the thousand and one adulterants that weaken the strength of a sentence.

Clear thinking becomes clear writing; one can't exist without the other. It's impossible for a muddy thinker to write good English.

Thinking clearly is a conscious act that writers must force on themselves.

Writing is a hard work. A clear sentence is no accident. Very few sentences come out right the first time, or even the third time.
Tell me, and I will forget. Show me, and you will involve me. Involvement is the first step toward understanding. If you're concerned about whether in any passage or chapter you are telling rather than showing, there are some questions you can ask yourself:

Are you allowing the reader to see what's going on? Showing means having actors do things that excite our interest, making those pages visual, letting us see what happens firsthand.

How to show? Sight is our primary sense. We prefer to witness an event. Which is why, we must show a story instead of tell a story. Show, don't tell.

Verbs are the most important of all your tools. They push the sentence forward and give it momentum. Active verbs enable us to visualize an activity because they require a pronoun or a noun or a person to put them in motion.

Make active verbs activate your sentences, and avoid the kind that need an appended preposition to complete their work. Use precise verbs.

Most adverbs are unnecessary. You will clutter your sentence and annoy the reader if you choose a verb that has a specific meaning and then add adverb that carries the same meaning.

https://www.quora.com/Why-are-adverbs-considered-to-be-evil

Mark Twain - If you catch an adjective, kill it !. Most writers erect a Great Wall against the process of eliminating all but a minimal number of adjectives and adverbs.

Most adjectives and adverbs are dispensable. The easiest ones to dispense with are "very" and "quite".

Adjective surgery can be painful until you practice it rigorously and examine the results.

There are several rules for determining which adjectives to keep:
An adjective that is a necessity
An adjective that stimulates the reader's curiosity and thereby helps move a strong along. Example: He has a pursued look, wouldn't work without the adjective. Moreover, the adjective raises curiosity about why he had the pursued look..

An adjective that helps the reader visualize the precise image you want to project.

An adjective of course modifies a noun. An adverb modifies a verb,. Most adverbs require the same tough surgery as adjectives.

Leah wished he would call soon. The meaning of soon is implied. The adverb is unnecessary. The sentence is stronger without it.

A frequent error is the use of two adverbs. She really, truly cared for him. Would you eliminate "really" or "truly"? You could take out either.

Before you begin eliminating all adverbs by rote, keep in mind that sometimes adverbs can be helpful. There are 2 adverbs in the following short sentence. Each conveys something different.

He ate heartily, happily.

Heartily connotes eating a lot, "happily" connotes taking pleasure. If it's the author's intention to convey both meanings, the adversb should be retained. He ate without either adverb tells us little.

The verb should agree in number with its subject. So a plural subject requires a plural verb, and a singular subject rquires a singular verb.
A test was completed last week. (singular)
Several tests were completed last week (plural).

Ensure that your verbs agrees with your subjects.
She works every day. (singular)
They work every day. (plural)

He has the answer. (singular)
They have the answer (plural).

Strong verbs shorten sentences and convey direct memorable messages.

Subjects connected by and require a plural verb.
The ceiling panels and fasteners have been fabricated.

The software designer and the graphic artist agree that we should market the new instructional manual immediately.

A personal computer and a photo copier are essential business tools today.

Note: Sometimes words connected by and become so closely linked that they become singular in meaning, thus requiring a singular verb:

Bacon and eggs is my favorite breakfast. My name and address on the inside cover. Simon & Schuster is an excellent publishing firm.

Singular subjects connected by either...or, neither...nor, and...not oly...but also require a singular verb.

Either the post-operative therapy or the inflammation is causing the acute pain.

Neither the district engineer nor the superintendent has approved the plans.

Not only the cost but also the design is a problem.

Place the adverbs only, almost, nearly, merely, and also as close as possible to the word they modify.

The engineer had almost finished the specifications.

Choose adverbs, not adjectives, to modify main verbs:

Our accounts predicted accurately that cash flow would be a problem.
The manager asked quickly for the up-to-date estimates.
The test engineers calculated roughly the expected power.

Prefer active sentences. Use a passive sentence when you don't know or don't want to mention the actor. A style that consists of passive constructions will sap the reader's energy.

Use a passive sentence when the receiver is more important than the actor.

Avoid wordiness:

Use concise, direct sentences. The principles of writing direct, concise sentences

The verbs should agree in number with its subject...So a plural subject requires a plural verb, and a singular subject requires a singular verb.

The geologist has completed the tests. (singular). The geologists have completed the tests. (plurarl).

A test was completed last week. (singular)

Several tests were completed last week. (plural)

Ensure that your verbs agree with your subjects.

She works every day. (singular)
They work every day. (plural)

She is the candidate. (singular).
They are the candidates. (plural)

Avoid vague use of demonstrative pronouns.
This is something to consider (better: This shortfall in payments is something to consider.)
These are difficult (better: These exercises are difficult.).

Indefinite pronouns used as subjects should agree in number with their verbs:

Anyone likes to receive a positive performance review. (Anyone = singular; likes = singular)

Several were contacted before we chose a final canddidate (Serveral = plural, were = plural).

All of the sugar was tainted. (All of the sugar = singular, was = singular).

All of the employees were notified of the new vacation policy. (All of the employees = plural, were = plural)