Use of verbs in titles

[julian-cable]

Previously, the style guide gave the following advice:

"Use the gerund form (noun form of verb) for titles, not the imperative mood. For example, "Testing the Product", not "Test the Product"."

Since then, it was decided no longer to mandate gerunds in titles. This advice was removed from the previous release of the style guide (5.1):
#318

We need to provide relevant updated advice here. The following style choices are available, with an example of each:

• Gerund: "Identifying Installation Methods"
• Imperative: "Identify Installation Methods"
• No verb: "Installation Methods"

In which situations would each of these options be preferred? Please provide your thoughts.
@nmuller66 @daobrien @sffrench

[dsacco15]

I know I wasn't asked but it caught my eye.

Gerund: "Identifying Installation Methods" - avoid or use sparingly
Imperative: "Identify Installation Methods" - use more often, lead with a verb.
No verb: "Installation Methods" - I don't have a use case where this would be appropriate - avoid.

Take or leave anything I commented on...
Dave

[julian-cable]

Thanks Dave. I agree with almost everything you said.
But in a lecture, is it really necessary to include a verb in all cases?
Consider this title: "Describe Linux File System Hierarchy Concepts". What value does "Describe" add? What might be an improved wording?

[dsacco15]

You are actually correct. I spoke a bit too soon. That’s a valid use case and “Describe” is somewhat worthless. What about Linux File System Hierarchies is important to know or do? That’s where a verb would be useful, otherwise a verb is not needed.

[julian-cable]

That wording seems rather verbose to me. What do you think of "About Linux File System Hierarchies"?

[alexpdp7]

We had this discussion a long time ago and I was surprised to know that using gerunds in headers is not some kind of standard. For more "procedural" books, I find them everywhere (I have more "prestigious" procedural books at my other flat, but the two more "prestigious" that I have handy are "Designing Data-Intensive Applications" and "Automate the Boring Stuff with Python", and they both use gerunds in headers [the first one, even in the book title; although the second has an imperative in the book title]).

The IBM style guide is quite prescriptive too:

https://www.ibm.com/docs/en/ibm-style?topic=format-headings

(scroll down to "wording") (although it does say that imperatives have their place)

I think at some points you struggle writing a verby sentence and you need to do contortions to write it- in this case, often using a noun-y sentence might be warranted. But I like verby sentences because we mostly teach students how to do specific things, but I found that we abused a bit "introducing", "describing", "understanding", which I find not useful at all. But "creating users", "installing XXX", etc. sound like very informative headers to me (while "create users" sounds weird to me in a lecture. But maybe because I'm not a native speaker).

[dsacco15]

@alexpdp7, gerunds are not forbidden and you mentioned a few use cases. They aren’t appropriate every time is all we are saying.

[daobrien]

I think we need to get away from absolutes, such as always, never, mandate, forbid, etc. Sure there are examples that we'd like to avoid (some are covered in the style guide, but it hasn't been reviewed in a while) but that doesn't mean we can't use them. I stole this from a file I'm working on right now, with some comments:

= Managing Ansible Project Materials Using Git
== Objectives
== Defining Infrastructure as Code (probably don't need "defining")
== Introducing Git (I need to work through this section to determine if there's a better heading.)
== Describing Initial Git Configuration (don't need "describing")
== Starting the Git Workflow (need to review the content first)
=== Examining the Git Log (need to review the content first)
== Working with Branches and References (maybe could remove "working")
=== Creating Branches
=== Merging Branches
=== Creating Branches from Earlier Commits
=== Pushing Branches to Remote Repositories
== Structuring Ansible Projects in Git
=== Roles and Ansible Content Collections
=== Configuring Git to Ignore Files

afaict, apart from those I commented, we need verbs, and using imperatives won't work here.

[julian-cable]

I am trying to think about what our revised guidance might be. Would it be something along the following lines:

Start a title generally with the gerund verb form, which ends with "-ing", for example "Creating Branches".
Use a verb to refer to specific actions that users take, such as "Configuring", "Creating", "Installing", and "Merging".

Avoid verbs such as "Describing", "Introducing", and "Understanding", which add little value. Either use a more specific verb, or omit the verb in those cases. For example, instead of "Describing Initial Git Configuration", you can use "Initial Git Configuration".

WDYT, @daobrien and others?

[nmuller66]

@julian-cable
I think this proposed text is fine, although it could perhaps better emphasize that the gerund form is not required.
If we are recommending that hand-on always use gerunds, then we should be specific about that.
I've seen a lot of movement away from using all gerund forms in some recent courses following the initial discussion we had with developers, which might have been an over-reaction.
I've tweaked the proposed text slightly. See what you think.

Usually, you start a title with the gerund form of a verb, which ends "-ing", for example "Creating Branches". Choose a verb that refers to specific actions that users take, such as "Configuring", "Creating", "Installing", and "Merging".

Gerund verb forms are not always required. For example, avoid verbs such as "Describing", "Introducing", and "Understanding" because they add little value.
Instead, use a more specific verb or omit the verb. For example, instead of "Describing Initial Git Configuration", you can use "Initial Git Configuration".

[julian-cable]

@nmuller66 Your update looks good to me. In the first sentence, I would just add "with" after "which ends".

[nmuller66]

good catch, thanks @julian-cable