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) form: (e.g. "Creating a Cluster", "Creating a Database", ...) - Descriptive form: (e.g. "Cluster creation", "Database creation", ...)
- Imperative form (e.g. "Create a Cluster", "Create a Database", ...)
- Any other ideas?
Which would be best for title names?
This post was sourced from https://writers.stackexchange.com/q/1545. It is licensed under CC BY-SA 3.0.
3 answers
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.
This post was sourced from https://writers.stackexchange.com/a/1551. It is licensed under CC BY-SA 3.0.
0 comment threads
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 comment threads
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 comment threads
0 comment threads