Writing Stack Exchange is a question and answer site for the craft of professional writing, including fiction, non-fiction, technical, scholarly, and commercial writing. It only takes a minute to sign up.
Sign up to join this community
I'm writing a technical manual about creating database systems, and wondered what is the best verb tense for title names.
My ideas are:
-ing) form: (e.g. "Creating a Cluster", "Creating a Database", ...)Which would be best for title names?
-ing. I am a tech writer, and this is typically how we word titles of sections that focus on how to accomplish a task.
As a long-time technical writer, I agree that the gerundive (continuous) form is most common in titles. That is IBM style (at least it was while I was there).
What is more difficult to fathom is that the present tense (and imperative) should be used whenever possible in the text. "First, prepare your storage medium. To get the most from your hard drive, polish the disk surface to a gleam using a mildly abrasive cleanser." You would not say: "First you will prepare your storage medium." Nor would you use the continuous form in the text: "Polishing your hard disk with a mildly abrasive cleaner is a way of getting the most from your hard drive." Avoid passive construction if you possibly can. Finally, there are occasions to use past tense, but they are rare.
(Please recognize my quoted examples as pure flights of fancy. I know what Vim would do to a hard drive. :-) )
I like "Create a Cluster." If I'm actually RTFM, I'm usually looking for instructions on how to do something. Well, what do I want to do? I want to Create a Cluster — so that's what I'm going to look for. (That said, I don't mind the -ing form either.)
"Cluster creation" seems unnecessarily passive to me.
The choice between Continuous/Progressive form and Imperative form is one of style. Choose one form and use it consistently. In my experience, I've heard plenty of strongly held opinions about which is correct, but seen no convincing evidence that it makes any difference.
I can't back this up, but if you have a significant audience of non-native English speakers, the Imperative form might be better as it uses the more familiar form of the verb. Someone with localization experience could give you guidance on this.
Another issue to consider is context. What kind of documentation are you writing? If it's proscriptive, how-to content such as a getting started guide, the Continuous or Imperative forms will be most appropriate. In this kind of doc you're typically organizing content by task, so the task should lead the title. For example, you might have chapters/pages/sections like this:
If the content is reference material, you may want to organize by subject, so you'd do this instead:
Within the Databases chapter you'd probably have sections on creating and deleting. (Note that Load Balancing here is a gerund form, which is different from the Continuous/Progressive form.)
Looping back to the beginning, these are style issues that should be documented and followed consistently. Users are far more confused by inconsistency in style and usage than even arbitrary usage if followed consistently. So you want to choose terms and forms and then use them all the time. To many users these are all different:
Write down your style choices. You will forget. If you work with other people, they will need to know so your work is consistent.
If you don't want to make these decisions on your own, that's OK. Other people have been down this road before and already created style guides. Something like the AP style guide, for example, will take you a long way.
It's often a matter of house style, if you are working with a publisher, and the style can vary within the same publisher, depending on the series. I've written many books for Peachpit Press, and they have two popular series with different styles. For example, imagine you were writing a book on PowerPoint (as I have). In their Visual QuickStart Guide series, I wrote "Creating a Slide." In their Visual QuickProject series, the task was "Create a Slide." Both series of books are step-by-step instructions, and I found that either form works. The Imperative tends to take up a bit less space in the header, which was important in the QuickProject series design.
I'm more comfortable with the Continuous form (perhaps because I've written many more Visual QuickStart Guides). I think that it's friendlier and invites the reader to follow along with you; I'm personally a bit put off by the Imperative form. The Continuous form was also the one required by the Dummies books that I did.
Imperative has my vote, by far. It is the clear winner in my professional opinion (IMPO) for the types of tech docs I write and most types I read and edit. I write mostly end-user how-to guides with step-by-step procedures and a few introductory and "about" guides or parts of guides.
Note, too, that I avoid -ING words if possible and follow global English guidelines. This is primarily because some languages have no equivalent to -ing words. Literally: -ing words don't translate to some languages. In today's global world, whether my docs are translated by my company or not, for years I've written with the assumption that many of my readers are reading English as a second language (ESL) and they either programmatically (browser or other tools) or in their minds translate my text into their own language.
Literacy rates, especially in the US, are at all-time lows, too. So, IMPO, the more simple that I can write tech docs, the better for all readers. I define "KISS" as "keep it super simple".
References:
John R. Kohl's still-relevant and seminal book, The Global English Style Guide, devotes an entire chapter (22 pages) to "Clarifying -ING Words". The book, ©2008, is hard to find and not online. But, it is still relevant and worth the trouble to locate a copy and incorporate its key points into your tech docs (even as I write this in October 2022). There is no equal that I'm aware of.
Edmond H. Weiss, in The Elements of International English Style (p. 25) states, "Some forms of controlled English severely restrict the use of words ending in "ing" because of the several problems associated with this suffix." That section of the book focuses on use of the simplest verb forms.
Microsoft Writing Style Guide (https://learn.microsoft.com/en-us/style-guide/global-communications/writing-tips accessed 10/17/22) says, in their Tips for all global content section, "Use words ending in –ing carefully. A word ending in –ing can be a verb, an adjective, or a noun. Use the sentence structure and optional words to clarify the role of the –ing word." (Note that, regretably, Microsoft uses "ending" twice in its description of why writers should use -ing words with care for global audiences.)
For an unvarnished take on -ing words, see https://www.wyliecomm.com/2021/04/stop-it-with-the-ing-ing-headlines/.
Also, refer to https://en.wikipedia.org/wiki/Gerund, which focuses on -ing words as gerunds and covers some of the pitfalls of use of them.
The Microsoft Style Guide says it depends on usage:
In general, use imperative constructions in conceptual or informational topics for both the title and the headings. Describe what the user wants to do in the user’s language.
For material that does not describe a task, use a noun phrase, not a gerund phrase, a prepositional phrase, or a clause. (4th edition, p. 134-135)
They give as examples "Find a File" for the former and "Error Messages and Their Meanings" for the latter.
My group has decided that gerunds are acceptable for conceptual sections (for example, "Monitoring Performance"), though many conceptual topics call for noun phrases. So we use a mix. We have found that the imperative style only works for fine-grained tasks: "Create Keytab File" but not "Configure Kerberos" (the latter being a large task calling for the user to make decisions).
Continuous form (-ing) in chapter/section titles acts refreshingly on me. So I prefer it.
I am not aware of any formal guidelines, but here is my subjective take:
I would choose the appropriate one based on the target audience for the document.
I have settled on using gerund form for main section heads, and an infinitive form for specific (numbered) procedures. I do not recommend imperative form because doing something is often a choice, but imperative form makes everything sound mandatory.
I also use simple noun form for "overview" and "introduction" sections ("Overview of database design" and "Introduction to indexes")
Here is an example of the gerund and infinitive form:
Section heading: "Working with wood"
Procedure subheading: "To cut a board"
Procedure subheading: "To join two boards"
