Clarify guidance for using gerunds

[rclee33]

Currently, there is a note in section ⁠3.2 Heading Styles after Table 3.1 that says to avoid using gerunds outside of titles and redirects the reader to consult section 2.6 Sentence Structure.

However, gerunds are not discussed in Section 2.6.

As well, we should provide more nuanced guidance about the use of gerunds, rather than simple yes/no.

For example, the following sentences contain examples of gerunds that are used effectively (in one case, after verbs, and in another case, at the start of a sentence):

• "Containers also modularize applications to improve developing and maintaining their individual components."
• "Running containers at scale requires a container platform, such as Kubernetes, to manage networking, high availability, and configuration."

Cases where not to use gerunds include after a noun in most cases, whether or not a comma intervenes.

[julian-cable]

The good examples of gerunds in the previous comment came from the following PR:
https://github.com/RedHatTraining/DO180/pull/2069

In most cases, gerunds should be avoided when they occur after a noun, because such a construction can be ambiguous and can cause difficulty for translation.

Examples:

"The nmap utility scans privileged TCP ports looking for services."
To improve, change "looking" to "by looking" or "that look", depending on the meaning.

Investigate this issue using the log files on the servera machine.
To improve, change "using" to "by using" or "that uses", depending on the meaning.

Also, avoid a noun followed by an "ing" word if a comma intervenes.

Examples:

"The Traffic flows table displays dropped bytes and packets in red text within the existing Bytes and Packets columns, enabling you to quickly identify flows experiencing packet loss."
To improve, change "enabling" to "which enables", or rewrite in another way, such as "... columns, so you can quickly identify ...".

"An optional 12-month add-on can extend the total support to 36 months, providing stability for mission-critical production environments."
To improve, instead of "providing", use "which provides", or "to provide", or other wording.

Exceptions:

In some specific cases, a noun followed by an "ing" word comprises a single entity, and should be retained in this format.

Examples:
performance tuning
error logging

[rclee33]

For the additional examples showing when to avoid gerunds: I agree that the sentences must be updated for clarity, but I don’t think those instances of -ing verbs are gerunds.

To ensure that we’re on the same page: a gerund is an -ing verb form that functions like a noun ("Reading is my favorite hobby").

But in these cases, the -ing verbs are part of an adverbial phrase; they are modifying other verbs in the sentence, and they are not functioning as nouns.

Example 1: "The nmap utility scans privileged TCP ports looking for services":

• "looking for services" modifies the verb "scans"
• It describes how/why the scanning happens (while looking for / in order to look for)
• It's not functioning as a noun

Example 2: "Investigate this issue using the log files on the servera machine."

• "using the log files" modifies the verb "investigate"
• It describes how to investigate (by using / with the use of)
• It's not functioning as a noun

Example 3: "The Traffic flows table displays dropped bytes and packets in red text within the existing Bytes and Packets columns, enabling you to quickly identify flows experiencing packet loss."

• "enabling you to quickly identify flows experiencing packet loss" modifies the entire main
  clause
• It describes the result or purpose of displaying information in red text
• It's not functioning as a noun

For some of these cases, the Style Guide already contains guidance to help improve them, such as to use relative pronouns and to avoid ambiguous “using”.

But, I am noticing a significance increase of the last example (-ing words following a comma), which are often ambiguous and unclear.

I do think it could be helpful to provide guidance about that particular issues, but as separate guidance from gerunds.

[rclee33]

@julian-cable Raised a great point offline that many folks might struggle to articulate the difference between gerunds and other -ing verb forms.

Perhaps the solution here is to create a generic section about using -ing verbs or -ing words, which could include a range of use cases -- including gerunds.

For example: "Using -ing Verb Forms"

1. Explain the distinction between gerunds (nouns) and present participles (modifiers)
2. Provide clear examples of each
3. Give guidance on which uses to avoid vs. which are fine