Comedy writers seek the funniest results, horror writers strive for thescariest, and technical writers aim for the clearest. In technical writing,clarity takes precedence over all other rules. This unit suggests a few waysto make your sentences beautifully clear.

Choose strong verbs

Many technical writers believe that the verb is the most important part of asentence. Pick the right verb and the rest of the sentence will take care ofitself. Unfortunately, some writers reuse only a small set of mild verbs,which is like serving your guests stale crackers and soggy lettuce every day.Picking the right verb takes a little more time but produces more satisfyingresults.

To engage and educate readers, choose precise, strong, specific verbs.Reduce imprecise, weak, or generic verbs, such as the following:

• Forms ofbe: is, are, am, was, were, etc.
• Occur
• Happen

For example, consider how strengthening the weak verb in the followingsentences ignites a more engaging sentence:

Many writers rely on forms ofbe as if they were the only spices on the rack.Sprinkle in different verbs and watch your prose become more appetizing. Thatsaid, a form ofbe is sometimes the best choice of verb, so don't feel thatyou have to eliminate every form ofbe from your writing.

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

• An imprecise or missing actor in a sentence
• A passive voice sentence

Exercise

Clarify the following sentences by picking more specific verbs. Along the way,feel free to rearrange the sentences and to add, modify, or delete words:

1. When a variable declaration doesn't have a datatype, a compiler errorhappens.
2. Compiler errors occur when you leave off a semicolon at the end of astatement.

Reduce there is / there are

Sentences that start withThere is orThere are marry a generic noun toa generic verb. Generic weddings bore readers. Show true love for yourreaders by providing a real subject and a real verb.

In the best-case scenario, you may simply deleteThere is orThere are(and possibly another word or two later in the sentence). For example, considerthe following sentence:

There is a variable calledmet_trick that stores the current accuracy.

RemovingThere is replaces the generic subject with a better subject.For example, either of the following sentences is clearer than the original:

A variable namedmet_trick stores the current accuracy.

Themet_trick variable stores the current accuracy.

You can sometimes repair aThere is orThere are sentence by moving thetrue subject and true verb from the end of the sentence to the beginning. Forexample, notice that the pronounyou appears towards the end of thefollowing sentence:

There are two disturbing facts about Perl you should know.

ReplacingThere are withYou strengthens the sentence:

You should know two disturbing facts about Perl.

In other situations, writers start sentences withThere is orThereare to avoid the hassle of creating true subjects or verbs. If no subjectexists, consider creating one. For example, the followingThere is sentencedoes not identify the receiving entity:

There is no guarantee that the updates will be received in sequential order.

Replacing "There is" with a meaningful subject (such asclients) createsa clearer experience for the reader:

Clients might not receive the updates in sequential order.

Exercise

Clarify the following sentences by removingThere is,and possibly rearranging, adding, modifying, or deleting other words:

1. There is a lot of overlap between X and Y.
2. There is no creator stack for the main thread.
3. There is a low-level, TensorFlow, Python interface to load a saved model.
4. There is a sharding function nameddistribute that assigns keys.

Minimize certain adjectives and adverbs (optional)

Adjectives and adverbs perform amazingly well in fiction and poetry. Thanks toadjectives, plain old grass becomesprodigal andverdant, while lifelesshair transforms into somethinglustrous andexuberant. Adverbs pushhorses to runmadly andfreely and dogs to barkloudly andferociously. Unfortunately, adjectives and adverbs sometimes make technicalreaders bark loudly and ferociously. That's because adjectives and adverbs tendto be too loosely defined and subjective for technical readers. Worse,adjectives and adverbs can make technical documentation sound dangerously likemarketing material. For example, consider the following passage from a technicaldocument:

Setting this flag makes the application run screamingly fast.

Granted,screamingly fast gets readers' attention but not necessarily in agood way. Feed your technical readers factual data instead of marketing speak.Refactor amorphous adverbs and adjectives into objective numerical information.For example:

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

Does the preceding change strip the sentence of some of its charm? Yes, alittle, but the revamped sentence gains accuracy and credibility.