A recent manager insisted that I was never allowed to include the word “use” in any technical documentation I wrote because it was a weak verb and the manager said there was now a hard-and-fast rule about never using weak verbs. It was an all-out war on “use.” When I asked what the manager would prefer, I was given a list of “appropriate” verbs. I disagreed with this blanket rule then, though I followed orders, and I still disagree.
I hold that it’s not weak verbs that are a problem in most technical documentation. The bigger issue is the use of passive voice. But I wanted to think about and examine the use of weak verbs in technical documentation, especially API documentation.
In my own case instead of “use”, I had to make do with verbs like “invoke,” “implement,” or even “utilize.” (Some of you will immediately see that those examples are also considered to be weak verbs, though the manager allowed them. I always love blanket rules and mandates that are not consistent nor correct.)
Now, to be fair, some technical content may benefit from the use of carefully chosen strong verbs. API reference material, on the other hand, and even some API conceptual material, benefits more from being clear and consistent than from a demonstration of vocabulary. Technical documentation, as a whole, also benefits from a proactive prevention of potential localization or translation problems–but more about that in a later post.
A key thing to understand before I talk about the differences between strong and weak verbs is that, despite the implications of “weak” and “strong”, a weak verb is not intrinsically inferior or bad. A strong verb is not automatically better or more desirable. They are both useful tools and the key to success is how you use them and when.
What are weak verbs?
To determine if a verb is “weak,” you look at what is required to turn the verb into its past tense or past participle form. A verb is considered weak if:
- You can add a -d, -ed, or -t to the verb, not change its pronunciation, and obtain its past tense or past participle. For example, use -> used, utilize -> utilized, and manage -> managed.
- You can add a -d or -t to the verb, change its pronunciation, and obtain its past tense or past participle. For example, weep -> wept, sweep -> swept, and kneel -> knelt.
- You can retain the -d or -t of the verb, shorten the vowel sounds, and obtain its past tense or past participle. For example, bleed -> bled, breed -> bred, and meet -> met.
- You can not change the verb and obtain its past tense or past participle because the verb is the same in present as well as past tense. For example, set -> set, wed -> wed, and bet -> bet.
Instructors and editors often discourage the use of weak verbs because they are considered nondescript and often contribute to passive voice in writing. Strong verbs, by definition, add nuance and connotation to writing.
Weak vs strong verbs
However, in technical documentation, especially API documentation, nuances and connotations often result in confusion and distraction for those using the documentation. They also cause a host of localization and globalization issues. API documentation is one of the many types of technical documentation in which weak verbs serve the user well and are often the perfect choice.
Here are some examples of weak vs strong verb usage:
Use vs Invoke:
- Use Method A to obtain a list of all class members.
- Invoke Method A to obtain a list of all class members.
In the first example, the sentence is straightforward and doesn’t really have any nuances. The first definition of “use” on Dictionary.com is “”to employ for some purpose; put into service; make use of”.
In the second example, there are several issues. One is that the word “invoke” is too formal for the rest of the sentence, but that’s a style consideration. The bigger issue is that “invoke” has ceremonial and religious connotations that don’t apply within API documentation. The first definition of “invoke” on Dictonary.com is “to call for with earnest desire; make supplication or pray for”. That definition is not applicable to an API or what the user will attempt to use the API to accomplish.
Respond vs Come Back:
- The server will respond with a list of all class members in the specified class.
- The server will come back with a list of all class members in the specified class.
In the first example, the second definition on Dictionary.com for “respond” is “to make a return by some action as if in answer”. Because I am talking about an API request, respond is the most natural verb to use and arguably the most accurate. The user has asked the server for information and the server has responded with the requested information.
In the second example, the first definition on Dictionary.com for “come back” is “to approach or move toward a particular person or place”. Well, no, that doesn’t have much at all to do with a server response. And what will “come back” anyway?
Nuances and connotations can be increase confusion
Because strong verbs have connotations, those connotations can actually increase confusion. The religious implications in the use of “invoke” in the first set of examples is clearly not applicable to technical documentation, so the user is left to wonder what exactly the documentation means.
In the example with “come back”, what exactly does that mean? Will the server send back information? Will it write that information to disk? Respond implies a like transaction to the request but come back is completely unknown other than it carrying the connotation of a reaction.
I’ve been distracted more than a few times when trying to use documentation written by someone else. I’ve run across non-typical verbs and stopped to try to figure out what in the world was actually intended. The most recent was the use of “petition” used in place of “request” in a procedure step that read “Click Send to petition the server for access.” This stood out because petition is far too formal a word for this sentence, but also because of the connotation that it was a written or formal entreaty. To be fair, one of the less common meanings for petition is “to beg for or request (something)” but the connotations just got in the way when I read that sentence.
Instead, I’d rewrite that step to say “Click Send to request access.” or, if I needed the differentiation of “server”, I’d rewrite it to say “Click Send to request server access.”
Easier, cleaner, and difficult to misinterpret.
Consistency makes a big difference
Another complaint about weak verbs is that they are nondescript. It’s actually better to consistently use a set of nondescript verbs throughout the API documentation than it is to seek out alternate or stronger verbs to sprinkle in. API documentation is meant to teach users how to use the API and a standard, consistent vocabulary removes the need for guesswork on the part of the user. Standardized verbs also lets users know what to expect and a deviation from the standard list will draw their attention, when needed.
Other types of writing, from marketing communications to fiction writing, value a wide variety of verbs and descriptors but that is because they are trying to evoke emotion and action with the nuances and connotations in their writing. Technical documentation, on the other hand, is less about emotion and more about instruction and explanation.
Adding your chosen verbs to your style guide and standardizing on them will be a benefit throughout a documentation project. Many style guides include guidance on how to tell the user to click on a button, follow a link, or insert text. If you add your verbs to the style guide, you can add consistency to their use as well.
Passive voice is a bigger issue than weak verbs
Weak verbs are really not the problem in technical documentation. The real problem is passive voice. If your documentation uses forms of “to be” as a sort of “helper” verb, you are probably writing in passive voice.
- Active: The server provided a new token.
- Passive: A new token was provided by the server.
You’ll notice that the verb in the active sentence is still a “weak” verb, yet the sentence is clear and concise. The passive sentence has more words and less clarity. It’s a poor writing style to use for technical documentation (among other types of writing). If you avoid passive voice and choose clear and consistent verbs, you will have a good start toward effective technical documentation. Don’t rely on an arbitrary rule against weak or strong verbs to improve your documentation.
Photo credit: Biking Nikon SFO / Foter.com / CC BY-NC-ND
Pingback: API Documentation: Don’t Create a Localization Nightmare – Maura van der Linden
I think “invoke” is the correct verb for API documentation for some programming languages. Some programming languages refer to it as a “method invocation”, others as a “method call”. So I would say that it’s a technical term with a specific meaning. Therefore the considerations about weak verbs do not apply.
The verb “respond” is similar. In a client-server architecture a client makes some use of a service provided by the server. If the client does so through a RPC or RMI, the servers “returns” a certain result for the remote procedure call or method invocation. Most programming languages even use the keyword “result”. If the client makes use of the service by a message passing and the interaction pattern is synchronous request-reply, I would use the verb “reply” or “response”. The verb “comes back” tells me that the interaction is strictly asynchronous, i.e. that the client shouldn’t wait for an immediate response from the server and should do some other work while waiting for it. So “comes back” only says that the server will provide a result but not when. There might be a long time between the request and the response.
So I think you have to consider the specific use of the verbs and their specific meaning to avoid confusion about technical details and make the documentation short and easy to understand.