10 Minimalist Principles for Good Technical Writing

Principle Four: Choose Verbs with Care

This article is part of a series of articles entitled 10 Minimalist Principles for Good Technical Writing.

Broadly speaking, minimalism is any style or technique that is characterized by an extreme reduction to necessities and radical simplification. A minimalist is a person who strives to restrict the means and ends required to achieve a goal to a minimum. Applying minimalist principles to writing can support the key objective of technical communication: to enable users to learn and accomplish as much as possible, on their own, in as short a time as possible.

Principle Four: Choose Verbs with Care

The power of verbs

A verb is usually the word in a sentence that is essential to the structure and meaning of the sentence. Therefore, verbs and how they are used can sometimes make or break the clarity of the intended message.

Verbs with multiple meanings

verb + preposition or adverb

As described in Principle One: Keep Sentences Simple, some verbs can be combined with a preposition or an adverb to convey a special meaning, for example, change over, fill in, turn on, or phase out. These types of verbs are called phrasal verbs. Phrasal verbs such as log on,set up, and switch off are widely understood in information technology; however, some phrasal verbs are ambiguous because they can have multiple meanings.

Example:

  1. make up: comprise, design, invent, reconcile, represent, settle, …
  2. put off: avoid, circumvent, defer, delay, postpone, repel, …

If the meaning of a phrasal verb in a given context is not clear, it is sometimes better to choose another verb or rephrase the text.

Example:

  1. Phrasal verb: Do you want to put off the installation of updates?
  2. Verb: Do you want to postpone the installation of updates?
  3. Verb + adverb: If you want to install updates later, choose Remind me later.

In the third example, the verb “install” shifts the focus of the sentence to the primary action that needs to be performed.

Verbs for expressing actions

verb + noun vs. verb only

The verb in a sentence is mostly concerned with the action. An easy way to simplify a sentence and, if applicable, emphasize the action that users need to perform is to reformulate the noun in the sentence as a verb.

“Action!”
Action!

Example:

  • to perform an installation vs. to install
  • to make the configuration settings vs. to configure
  • to make changes vs. to edit
  • to make payments vs. to pay

Adverbs for adding information

verb + adverb vs. verb only

An adverb is a word that adds information to a verb. Different categories of adverbs communicate different kinds of information, such as:

  • When something happens (for example, now or later)
  • How something happens (for example, automatically, quickly, spontaneously)
  • The impact of what happens (for example, moderately, partially, totally)
  • How often something happens (for example, rarely, occasionally, frequently)

Therefore, adverbs have an important function because they modify the words to which they apply and provide more specific information about an event. However, in some cases, an adverb is not necessary if a more specific verb is chosen.

Example:

  • to make run more smoothly vs. to optimize
  • to work together well vs. to cooperate
  • to arrange logically vs. to structure

A more specific choice of verb can eliminate the need to use an adverb and result in a shorter and simpler sentence.

Verb vs. noun: Same word, different meaning

“Gimme a break”, “Break a leg!”

The English language comprises an abundance of words that can mean different things and have a different grammatical form depending on the context. For example, words such as break, cache, change, display, host, log, monitor, search, speed, use, and work can be both verbs and nouns.

Example:

  1. Verb: Data is cached.
  2. Noun: Data is stored in the local cache.

Further examples of verbs that can also be used as nouns are irregular verbs that have the same form in the infinitive, past tense, and past participle forms and do not end in -ed, such as cost, run, and split.

Words that can be both verbs and nouns are problematic because users can misinterpret them, especially when they occur in sentences that have other language issues such as a long string of nouns, which are also known as noun clusters.

Example:

  1. The site monitors configuration settings is for administrators only.
  2. Only administrators can configure the monitoring settings of the site.

In the first sentence, “monitors” could be understood as the plural form of the noun monitor or as the third person singular of the verb monitor. Furthermore, a user might think that the site is doing the monitoring whereas the action of the sentence is the configuring which is done by administrators. Therefore, the true meaning of the sentence is clearer in the second sentence where the verb “configure” is the action in the sentence and the noun cluster is split up.

Direct and clear commands

Imperative mood: instructive not commanding
commanding officer

Like the active voice (see Principle Three: Use Active Voice), the imperative mood is direct and clear because verbs in the imperative mood express commands or a call to action on the part of the user. For this reason, imperative sentences are especially effective in step-by-step procedures, for instructions, for tips and also for UI controls and icon tooltips.

Example:

  1. Step: Sign in to OpenDox by entering your account credentials.
  2. Instruction: Restart your computer now.
  3. Tip: Check your network connection.
  4. UI button: Add to Cart
  5. UI checkbox: Ask to save logins and passwords for websites.
  6. Burger menu icon: Open menu
Direct commands are in users’ interests.
Use crosswalk

Some people hesitate before writing imperative sentences because they fear that users will find the tone bossy or impolite. However, most users are familiar with imperative sentences and are not the least bit offended by their directness. The examples are all commands that are formulated as concisely as possible to enable users to understand something or grasp what they need to do as quickly as possible.

Verbs for expressing tense and nuance

Verbs such as be, do, and have are used as “helping” verbs (auxiliary verbs) to convey the tense, mood, and voice of other verbs.

Example:

  1. Present perfect tense in passive voice: A new version of OpenDox has been released.
  2. Interrogative with modal verb: Do you want to install updates now?
  3. Future tense in passive voice and present perfect tense: Your settings will be applied after you have restarted your computer.
Present tense is often best.

In technical writing, the present simple tense helps users scan text more quickly than text that is written in past or future tenses. Sentences that use the present tense are often shorter than sentences that use other tense. In technical communication, generally you only need to use past and future tenses if there is no other way to describe the order of events.

Example:

  1. Future tense in passive voice and present perfect tense: Your settings will be applied after you have restarted your computer.
  2. Present simple in passive voice and present simple: Your settings are applied when you restart your device.
Modal verbs often lack clarity.

Modal verbs such as can/could, may/might, shall/should, want/wish, and will/would are a type of auxiliary verb and express nuances of ability, possibility, probability, wants, wishes, necessity, permission, recommendation, and suggestion. In technical writing, modal verbs need to be used with care because they often lack the clarity that users need to understand whether an action is possible, optional, mandatory, or recommended. For example, “can” and “may” are often confused, which is why it is often better to avoid “may” and other modals verbs such as shall, should, could, and might, by using more specific verbs or wording.

Example:

  1. Ability: The default variable is 10. You can change the variable during operation.
  2. Permission: The default variable is 10. Only administrators have authorization rights to change the variable during operation.
  3. Necessity: The default variable is 10. You must change the variable during operation.
  4. Recommendation: The default variable is 10. We recommend that you change the variable during operation.

From actions to results

In technical writing, choosing verbs with care to emphasize the most important action in a phrase or sentence is an effective means for giving users actionable information in a clear and concise way. And actions that are well communicated are easier for users to perform correctly which in turn makes it easier for them to accomplish tasks.

Next up:

Principle Five: Negate with Purpose

  1. Keep sentences simple
  2. Use parallelism
  3. Use active voice
  4. Choose verbs with care
  5. Negate with purpose
  6. Organize information logically
  7. Communicate visually
  8. Aid navigation
  9. Be consistent
  10. Focus on what is important

About Helen Fawcett:

In a nutshell, I optimize user interface text such as control labels and create on-screen instructions and help documentation for developers & customers. | Helen works as a user assistance lead at SAP SE.
More about me
Home Minimalist PrinciplesTechnical WritingWriting Style Principle Four: Choose Verbs with Care