Death of the gerund in technical documentation
Actually, I’m fond of the gerund myself. I’m not seriously proposing we kill it, but I’d love to know what everyone thinks about using, or not using, gerunds in headings and page titles.
A gerund is an “-ing” word, like “adding” or “removing”. More specifically, it’s the “-ing” form of a verb when used as a noun. Most technical documentation uses gerunds in topic titles and page headings, like this:
- Adding a widget
- Deleting a widget
- Installing a widget
Examples of the traditional way:
Brave new world
We’re trying an experiment with short-form verbs in headings. Instead of gerunds, we’re using just the verb stems. So, instead of “adding a widget” we’re saying “add a widget”. This looks like an imperative, but it’s not meant as such. It’s just a short form of the verb, and more likely to match what people will search for on the page (using Ctrl+F, for example). It’s tempting to cite web searches as well, but any search engine worth its salt will find the stem of the word and return all results matching the stem.
Examples from our documentation:
- Markers, in the Google Maps JavaScript API.
- Map Objects, in the Google Maps Android API.
At the moment, we’re leaving gerunds in the page titles (primarily for consistency across the documentation suite) and just changing the headings within the pages.
Others who’ve killed the gerund:
Posted on 12 October 2013, in technical writing and tagged gerunds, grammar, headings, style, technical documentation, technical writing, titles, verbs. Bookmark the permalink. 23 Comments.
ffeathers 
When writing docs, I ask, “What does the user want or need to do?” The obvious answer is, “The user wants to adding a widget.”
My gerunds all went to pasture. They now peacefully graze with their prefect cousins.
Hallo Kelly!
Nice one. 🙂 Do you have an example of the resulting docs that people can see online?
Cheers
Sarah
Sorry, no. Maybe soon.
I have always had a keen interest in words. I recall being awestruck at the profound philosophical/grammatical wisdom of the Bee Gees, “They’re only words, and words are all I have…”
Fortunately for me, and to the chagrin of many of my acquaintances, I went to Catholic school, where we were drilled in tenses, and conjugation. We actually had contests on things such as pluperfect, future perfect, and verb/noun tense agreement. Then it really got difficult when I went to Second Grade.
From a tweet: Donald H White is in favour of the declarative when answering the question “how do I x”.
One of my clients recently asked me to change the gerunds in headings to verb stems. It wasn’t my first choice, but I can see why it appeals to them. There’s something crisp and efficient about the topic title “Add a widget.”
Hallo Larry
That’s really interesting! A request from a stakeholder is telling.
Cheers
Sarah
One thing I don’t like about using the verb stem is that it can look and read like a noun phrase–and as you mentioned, “This looks like an imperative”, you don’t want your users to have to infer what you mean by a title (especially 1st-time visitors who are not familiar with your content approach–80% of my documentation’s visitors are 1st-time visitors). For example, “Map Objects” could easily be read as “as object that is a map”–in that case, “mapping objects” is much clearer as an action than “map objects”. I think that’s why “traditional” techcomm through current has stayed with the gerund–especially now, as you said, with stemming and other search tuning strategies. (last thing: using syntactic cues, ala John Kohl, is also useful for giving grammatical “hints” based on the syntax of the sentence).
Hallo ferswriteshoe
Oh now that’s a good point. In this case, “map objects” means “objects belonging to a map”. It’s not a verb, and it was misleading of me to use it as an example. (I was referring to the headings on the page rather than the page title.) And that illustrates your point beautifully. “Map” could be a verb or a noun. Possibly “mapping objects” would have been clearer, if it was intended as a verb. But there’s ambiguity there too. It all goes to show, we need to be very careful when crafting a title.
Cheers
Sarah
Consider these:
“How to Map Objects”
“How to Map Map Objects”
“You must map objects.”
“Mapping Map Objects”
I find language quite intriguing. Again with my assertion, “Written language is much different than spoken language,” consider how context changes meaning, how order changes intention. This fundamental is common with ESL speakers, but that’s only my perspective because I am a native U. S. English speaker. I am sure my spoken “second language” skills exhibit similar lessons in the importance of context and order.
When traveling, and my waitress asks, “What is eating you?”, I know immediately from context that the intention is to ask what I want for lunch. However, in the U. S., the same question is understood to be an interrogatory statement regarding my disposition.
I am sometimes transfixed as I ponder these subtleties of spoken language. Yet, I find even more psychologically interesting, the compensation we all make for broken rules of written language when listening, and the speed at which we compensate and respond.
At the company I previously worked, we removed all the ‘gerund-ing’ in headings. The reason give was that it was a translation issue.
Apparently, ‘add a widget’ translates to other languages more readily than ‘adding a widget’
Hallo Greg
Translation adds an interesting perspective. Did you run into any problems with languages that have a specific form for the imperative? It may be necessary to let the translators know when the imperative is required (such as in step-by-step instructions).
Cheers
Sarah
Hi Sarah:
I am afraid you have gotten out of my depth! I didn’t work directly with the translation company.
However, I have included what I think is the issue in a quote from an article by Betsy M. Maaks reprinted from Intercom magazine. http://tiinc.com/general_1.php
“Gerunds pose problems-they are nouns that look like verbs. Because nouns and verbs don’t perform the same grammatical function, it is best to use this construction only when you can surround it with other words (for example, “By gardening”), or avoid it altogether (for example, “How to garden” or “A garden is…”). The gerund requires interpreting, first to identify whether it is a noun or a verb, and then to convert it to an approximate meaning. Gerunds are a common convention in English headings, but I’m not aware of this noun form in other languages. So avoid gerunds like “gardening” and instead use a noun (“a garden”) or a verb form like an infinitive (as in “how to garden”).
Best,
Greg
We adopted that practice a little more than a year ago at WebAssign.
I agree with your experiment to use the stronger verb tense and to not use gerunds. I was taught years ago (maybe the good Sisters of St. Joseph in Holy Angels Grade School?) gerunds are weak and verbs are strong. It had something to do with the German roots of modern English, but it is a memory lost to the mists of time, now. Still, to this day, If I write a proposal, novel, speech, poem, procedure, technical manual, a letter, or any written work, I favor verbs over gerunds. Thank you, Sister Inez.
Hallo Bruce
That’s a cute story. 🙂 To complement it, today I came across this reference to The Private Life of the Gerund by Ronald Searle.
Cheers
Sarah
Here’s another gerund-related story I must mention:
It is now popular in US media, and marketing to create a gerund from a noun. One of the more egregious examples is the word “impact.” It is now common to hear, “The storm is impacting your town.” This is in contrast to the correct noun form, “The impact of the storm in your town.” With “impact” in particular, we also hear the root noun changed to a verb simply by using incorrect sentence structure. For example, “The storm impacted the town.”, but, I curmudgeon.
The gerund is in rude health in IBM user documentation topic titles (no, I did not write these particular examples). And IBM favors “Adding widgets” (plural) over “Adding a widget”.
Referring again to IBM user documentation: the wording of topic titles depends on the type of topic. For example, task topics are “verb phrases” (with a gerund). Concept and references topics are “noun phrases”.
(Saunters up to the Grammar Bar: “I’ll like a verb phrase with a gerund, please. Plural noun, hold the article. Sentence style capitalization, no terminating period.” “What’s that? It’s called style, my young friend. Save the twist of ascerbic wit for your blog. You don’t look old enough to conjugate.”)
LOL Graham, I suspect you’ve started a meme. “A tech writer walks into a bar…” Wait, that’s ambiguous. “A tech writer enters a bar…” Wait, could people think that means “types a bar character”? OK, how about, “A technical writer makes his or her way into a bar…” 😉
It is important to use the simplest and most readable language when talking about complexmsubjects such as code, so as not further complicate matters. So: die, gerund, die!
Btw, in the first example about map objects: “adding map code”…
I use whatever phrase the audience is most likely to quickly recognize and use in search engines.
Personally, I’m suspicious of keeping gerunds for grammar aesthetic or translation reasons. A good professional translator knows how to handle the languages he or she is translating. And however much we as writers appreciate grammar, this is usually lost on our audience. What they do appreciate are documents that are easy to find and read, that are complete yet hold attention. If a document fails to do this, in my experience, whether we use gerunds like a rosary or not is irrelevant to them.
How many of your customers can even distinguish a gerund or other verbal from a verb?
I looked through a sample of the 1300 or so pages of documentation I maintain. We don’t have a style guide. Gerunds appear in a few conceptual “about” topics but nowhere else. Many titles, paricularly at a higher level in the hierarchy, are simply the name of the “thing”: a noun. I use the short imperative form of verbs. Perhaps I am lucky, in that the documentation is for a system which deals with real-world things with names, not software with abstract concepts.
As Jakob Nielsen has shown, users scan lists reading as few words as possible from the left. If titles appear in a list, such as in a navigator, the first word should distinguish the topics. For that reason, I have no titles which begin “How to”. A gerund at the start of a title is often rather generic, such as “creating” or “editing”. This does not help the user scanning the list, unless its context is clear.
I can never think of gerunds without remembering Ronald Searle’s cartoons. Thanks for reminding me of them.
Adobe Framemaker name User Guide as “Using Framemaker 12”.