[On hold] Review and update guidance on using gerund verb form as the first word in a title of a procedure

[michelle-purcell]

Request:

Can we review the following guideline to always use the gerund verb form as the first word in a title of a procedure and consider allowing the bare infinitive verb form for task-based modules?

• The Red Hat modularization guidelines suggest that the title of a procedure module is a gerund phrase:
  

Non-goals: Please keep in mind that this proposal is not about reworking existing Red Hat docs. It simply allows some projects, like Quarkus, to have shared upstream-downstream content without expending extra work on titles.

See also the related CCS style guide council issue #256, who directed us to discuss this with mod-docs.

Many thanks :-)

Why are we asking?

The Quarkus docs team is moving to an upstream-first approach to developing product content. The upstream community content uses the Diátaxis framework for defining content types. In this framework, a Red Hat modularized procedure is closely mapped to a ‘how-to’ or a ‘tutorials’ topic. Both Diátaxis and the Quarkus style prefer the imperative verb form. They dislike and reject the guideline to use a gerund as the first word in the title of a procedure.

If Quarkus docs continue to align with Red Hat style and use gerunds as the first word in procedures in the product documentation, an effort will be required to ‘convert’ our titles from imperative verb form to gerunds. For example, we could use attributes to render bare infinitives upstream and gerunds downstream. This is not scalable or the best use of our time.

Overusing attributes adds complexity and in doing so we risk frightening off potential contributors who want to make a high-value update for technical accuracy.

More importantly, we do not believe that gerunds improve findability, usability, or the overall customer experience.

Arguments against using gerunds:

• Gerunds can be "ambiguous" because sometimes the reader can interpret the gerund as a noun, verb, or adjective.
• Gerund forms are inconsistently translated when they're used as the first word in a title.
• Gerunds increase character count in limited spaces, especially ToCs.
• The Diátaxis guidelines suggest gerund form is ambiguous and confusing.
• Encourages a consistent user experience for Quarkus readers that switch from upstream to downstream.
• SEO: Users don’t typically use the “ing” in their search queries. They use imperative verb form like "install", "configure", or "authenticate".
• SEO: Search engines include the “ing” as an alias and can find content without the “ing” in the search string.
• IBM Style guidelines state:
  “Use either a gerund or an imperative verb form for the subtasks of a high-level task.”
  The option to use either a gerund or the imperative form for subtasks can also lead to inconsistency/ambiguity depending on whether the writer decides if the task is mandatory or "not necessarily mandatory".
• Other well-known style guidelines advise against using the gerund form, for example, google developer style ⬇️ and popular technical writing articles.

Arguments for using gerunds

• Not as forceful and ideal for tasks that are not mandatory.
• Because all of our other docs use them.
• Because our style guide tells us to.

Can we revisit our guidelines and encourage using the imperative verb form instead of a gerund as the first word in a procedure or how-to topic?

Research points:

• The Red Hat supplementary style guide for product documentation does not mention any guidance about using gerunds.

• The Wording section of the Headings guidelines in the IBM style guide states:

  For a task procedure heading, use a gerund or imperative verb form. Use a gerund for a high-level task such as installing, administering, or troubleshooting. Use either a gerund or an imperative verb form for the subtasks of a high-level task. A gerund implies that a task is not necessarily mandatory, but rather that the task applies only if it is what the reader wants to do (for example, "Deleting obsolete entries"). The imperative voice is more prescriptive and implies that a step is mandatory (for example, "Ensure that prerequisite software is installed"). The imperative voice is also preferable for subtask headings that are used to create a list of steps in what is a larger procedure, such as a series of installation steps.

• The google developer documentation style guide advises: when possible, avoid using -ing verb forms as the first word in any heading or title.

  • An -ing verb form is a present participle or gerund. These verb forms are inconsistently translated when they're used as the first word in a title, and they increase character count in limited spaces.
    

• Write the Docs makes the point that gerunds …

  • Introduce a lot of visual repetition, which hinders skimming and causes noise.
  • Are inconsistent with how people browse the internet.
  • Can be challenging to translate and localize since some languages do not have identical counterparts.

• Tom Johnson from I’d rather be writing said he is thinking of saying goodbye to gerunds in topic titles.

References:

• https://www.writethedocs.org/blog/newsletter-october-2022/#gerunds-in-headings
• https://idratherbewriting.com/2008/02/11/are-gerunds-in-topic-titles-problematic-in-search-results/
• https://redhat-documentation.github.io/supplementary-style-guide/
• https://www.ibm.com/docs/en/ibm_style/headings.html
• https://redhat-documentation.github.io/modular-docs/#con-creating-procedure-modules_writing-mod-docs
• https://developers.google.com/style/headings

[bergerhoffer]

Hey all, just note that this issue was originally opened against the SSG (redhat-documentation/supplementary-style-guide#256) and we recommended it be brought here. See that SSG issue for some initial discussion on the topic.

[IngridT1]

Betty Prioux and I made a plea for the imperative (bare infinitive) form instead of gerunds quite a few years ago, but hardly anyone agreed with us then. I have no problem with allowing it in certain situations or for certain docsets (like Quarkus). I'd love it if we switched entirely to that form. I don't care for the idea of using a gerund as a major heading for procedures and the imperative for sub-headings or a list of subtasks in your docset, but I can understand the IBM Style argument. I'd say stick with one or the other throughout a docset. Best,

…

On Wed, Nov 16, 2022 at 4:33 AM Michelle Purcell ***@***.***> wrote: *Request:* Can we review the following guideline to always use the gerund verb form as the first word in a title of a procedure and consider allowing the *bare infinitive* verb form for task-based modules? - The Red Hat modularization guidelines <https://redhat-documentation.github.io/modular-docs/#con-creating-procedure-modules_writing-mod-docs> suggest that the title of a procedure module is a gerund phrase: [image: image] <https://user-images.githubusercontent.com/92924207/201975089-fa1978b7-e010-42f1-b3d8-822b46a55795.png> *Non-goals:* Please keep in mind that this proposal is not about reworking existing Red Hat docs. It simply allows some projects, like Quarkus, to have shared upstream-downstream content without expending extra work on titles. See also the related CCS style guide council issue #256 <redhat-documentation/supplementary-style-guide#256>, who directed us to discuss this with mod-docs. Many thanks :-) *Why are we asking?* The Quarkus docs team is moving to an upstream-first approach to developing product content. The upstream community content uses the Diátaxis <https://diataxis.fr/explanation/> framework for defining content types. In this framework, a Red Hat modularized procedure is closely mapped to a ‘how-to’ or a ‘tutorials’ topic. Both Diátaxis and the Quarkus style prefer the imperative verb form. They dislike and reject the guideline to use a gerund as the first word in the title of a procedure. If Quarkus docs continue to align with Red Hat style and use gerunds as the first word in procedures in the product documentation, an effort will be required to ‘convert’ our titles from imperative verb form to gerunds. For example, we could use attributes to render bare infinitives upstream and gerunds downstream. This is not scalable or the best use of our time. Overusing attributes adds complexity and in doing so we risk frightening off potential contributors who want to make a high-value update for technical accuracy. More importantly, we do not believe that gerunds improve findability, usability, or the overall customer experience. *Arguments against using gerunds:* - Gerunds can be "ambiguous" because sometimes the reader can interpret the gerund as a noun, verb, or adjective. - Gerund forms are inconsistently translated when they're used as the first word in a title. - Gerunds increase character count in limited spaces, especially ToCs. - The Diátaxis <https://diataxis.fr/> guidelines suggest gerund form is ambiguous and confusing. - Encourages a consistent user experience for Quarkus readers that switch from upstream to downstream. - SEO: Users don’t typically use the “ing” in their search queries. They use imperative verb form like "install", "configure", or "authenticate". - SEO: Search engines include the “ing” as an alias and can find content without the “ing” in the search string. - IBM Style guidelines state: *“Use either a gerund or an imperative verb form for the subtasks of a high-level task.” The option to use either a gerund or the imperative form for subtasks can also lead to inconsistency/ambiguity depending on whether the writer decides if the task is mandatory or "not necessarily mandatory".* - Other well-known style guidelines advise against using the gerund form, for example, google developer style ⬇️ and popular technical writing articles. *Arguments for using gerunds* - Not as forceful and ideal for tasks that are not mandatory. - Because all of our other docs use them. - Because our style guide tells us to. Can we revisit our guidelines and encourage using the imperative verb form instead of a gerund as the first word in a procedure or how-to topic? *Research points:* - The Red Hat supplementary style guide <https://redhat-documentation.github.io/supplementary-style-guide/> for product documentation does not mention any guidance about using gerunds. - The Wording section of the Headings guidelines <https://www.ibm.com/docs/en/ibm-style?topic=format-headings> in the IBM style guide states: *For a task procedure heading, use a gerund or imperative verb form. Use a gerund for a high-level task such as installing, administering, or troubleshooting. Use either a gerund or an imperative verb form for the subtasks of a high-level task. A gerund implies that a task is not necessarily mandatory, but rather that the task applies only if it is what the reader wants to do (for example, "Deleting obsolete entries"). The imperative voice is more prescriptive and implies that a step is mandatory (for example, "Ensure that prerequisite software is installed"). The imperative voice is also preferable for subtask headings that are used to create a list of steps in what is a larger procedure, such as a series of installation steps.* - The google developer documentation <https://developers.google.com/style/headings> style guide advises: when possible, avoid using -ing verb forms as the first word in any heading or title. - An -ing verb form is a present participle or gerund. These verb forms are inconsistently translated when they're used as the first word in a title, and they increase character count in limited spaces. [image: image] <https://user-images.githubusercontent.com/92924207/201980162-861d109e-bcd5-47c9-8537-fded5dc72b63.png> - Write the Docs <https://www.writethedocs.org/blog/newsletter-october-2022/#gerunds-in-headings> makes the point that gerunds … - Introduce a lot of visual repetition, which hinders skimming and causes noise. - Are inconsistent with how people browse the internet. - Can be challenging to translate and localize since some languages do not have identical counterparts. - Tom Johnson from I’d rather be writing <https://idratherbewriting.com/2008/02/11/are-gerunds-in-topic-titles-problematic-in-search-results/> said he is thinking of saying goodbye to gerunds in topic titles. *References:* - https://www.writethedocs.org/blog/newsletter-october-2022/#gerunds-in-headings - https://idratherbewriting.com/2008/02/11/are-gerunds-in-topic-titles-problematic-in-search-results/ - https://redhat-documentation.github.io/supplementary-style-guide/ - https://www.ibm.com/docs/en/ibm_style/headings.html - https://redhat-documentation.github.io/modular-docs/#con-creating-procedure-modules_writing-mod-docs - https://developers.google.com/style/headings — Reply to this email directly, view it on GitHub <#199>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AFTACS42LKL7HVSWY3JVXYLWISS63ANCNFSM6AAAAAASCAFCKE> . You are receiving this because you are subscribed to this thread.Message ID: ***@***.***>

-- Ingrid Towey Principal Technical Editor, Writing Coach

[bmcelvee]

I would support moving toward the imperative form. It would be more in line with industry standards, and as a bonus it would shorten our titles.

[emmurphy1]

The question is consistency and scannability. The decision to use gerunds in procedure titles predates my involvement with the modular documentation project. However, I imagine at the time these decision were made different options were proposed and voted on. While I personally do not have a strong preference for gerund phrases over imperative statements for procedure module titles, I do have strong reservations about changing the directive. If we do that, do we change all of the existing procedure module titles? Highly unlikey. So then do authors then decide for themselves to use one or the other, or just new procedure modules use imperative titles? Doing this will introduce inconsistency through our documentation and make documents harder to scan.

[emmurphy1]

I will add this to the agenda for the next review board meeting.

[michelle-purcell]

Thanks, @emmurphy1 👍

[rkratky]

I believe this thing shouldn't be codified by the mod docs guidelines in the first place. A recommendation? Sure, why not? But no strict rule. Let's either change the wording in the guidelines to allow for both forms (as the IBM SG suggests), or better yet, let's remove it altogether. The guidelines (should) deal with modularity, not language issues.

[bergerhoffer]

Whether this guideline exists in the modular docs guide or the supplementary style guide, I don't have a preference. But I do think we should have the guidance somewhere. Removing the guidance completely would let people pick whichever they want, and then there would likely be a lot of inconsistency even within a single product's doc set. And I don't think that's what we want.

If we want to allow flexibility for certain situations/projects to use imperatives instead of gerunds, that's fine with me. But I think we should still have a single approach as the default for all of product docs, so that we are as consistent as possible.

[inoxx03]

After discussing this issue at our latest CCS Style Council meeting, the I met with our writers on Quarkus docs and we re-evaluated our proposal to formalize the use of infinitive-form action verbs in procedure titles as an alternative to the currently recommended use of gerunds. We have decided to postpone our proposal to formalize this practice in both the SSG and the Red Hat Modular Documentation guidelines indefinitely.

For the time being Quarkus docs will continue to use gerunds in procedure titles, in what the CCS Style Council has deemed to be an acceptable deviation from guidance currently given by the SSG (Note, that even though this is a deviation from practice recommended by the SSG, the use of infinitives in procedure titles is still endorsed by the IBM Style Guide).

We are open to revisiting our proposal if we ever need to formalize this practice in the future.

@emmurphy1 @bergerhoffer Please feel free to close this issue (or keep it open, if you wish to revisit the matter in the near future.)

Thank you.

[bmcelvee]

For what it's worth, I'd like to keep the change from using gerund verb form to imperative on the table. It's more minimalist, modern, and in line with industry standards. This change would be immediately valuable for the ROSA and OSD documentation.

[inoxx03]

For what it's worth, I'd like to keep the change from using gerund verb form to imperative on the table. It's more minimalist, modern, and in line with industry standards. This change would be immediately valuable for the ROSA and OSD documentation.

@bmcelvee I second your opinion on this. I believe broadening the style options for writing procedure titles would be useful precisely for the reasons that you cite in your comment.
If we ever decide to revisit this discussion I'll be happy to participate in it again.

We might keep this issue open if most of us agree to do so.
The intention behind my original comment was to let our group of participants know that this is neither a priority issue nor a blocker for the Quarkus docs team at the moment. I have zero qualms with revisiting the question, or keeping it open for that matter:)

[emmurphy1]

Let's keep this open but put it on hold to reevaluate when we know what possibilities and limitations the new tool chain offers.

[michelle-purcell]

Thank you @emmurphy1, @inoxx03, @bergerhoffer, and all who contributed to this great discussion. 👍