: Verb tense for technical document titles I'm writing a technical manual about creating database systems, and wondered what is the best verb tense for title names. My ideas are: Continuous (-ing)

Vote Up Vote Down

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).

(0)

Vote Up Vote Down

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. :-) )

(0)

Vote Up Vote Down

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.

(0)

Vote Up Vote Down

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:

Create a Database
Manage a Database
Delete a Database

If the content is reference material, you may want to organize by subject, so you'd do this instead:

Databases
Clusters
Load Balancing

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:

Start the database
Launch the DBMS
Start a db instance.

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.

(0)

Vote Up Vote Down

I am not aware of any formal guidelines, but here is my subjective take:

Continuous: Seems less formal, like what I would expect from an online FAQ/guide.
Descriptive: This seems formal, like what would be required in a dry document, e.g. a government software requirements document.
Imperative: Also informal, like continuous. Seems more suited to step-by-step instructions, since it's telling the reader what to do.

I would choose the appropriate one based on the target audience for the document.

(0)

Vote Up Vote Down

-ing. I am a tech writer, and this is typically how we word titles of sections that focus on how to accomplish a task.

(0)

Vote Up Vote Down

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.

(0)

Vote Up Vote Down

Continuous form (-ing) in chapter/section titles acts refreshingly on me. So I prefer it.

(0)