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