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:



Android SDK
Confluence wiki

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:



Bitbucket
Splunk
Do you know of any more?


 •  0 comments  •  flag
Share on Twitter
Published on October 11, 2013 22:16
No comments have been added yet.