Add guidance for words to use and to avoid in headings

[stoobie]

I recall that in the class on constructing good headings, there was an issue with the word Understanding as the first word in a conceptual heading, such as Understanding containers. I don't recall what the issue was and I can't find anything that mentions the issue. Am I imagining things?

In any case, having a summary of the main ideas from that course in the style guide would be helpful, similar to the section on Minimalism.

[bergerhoffer]

I believe the reason to avoid "Understanding" in concept modules is that it is a gerund in a case like "Understanding containers", and gerunds are usually reserved for our procedure modules.

@IngridT1 is there anything else like this from that training course that would be useful to add to the SSG?

[jafiala]

Was it because it could mean "Containers that understand"? ;D

[IngridT1]

IBM Style has a guideline not to use "Understanding" in headings.

If the subject is a functional overview, end the heading with words such as Introduction or Overview rather than contriving a pseudo-task-oriented heading.

Incorrect example: Learning about the installation process
Correct example: Installation overview

Incorrect example: Understanding text analytics
Correct example: Overview of text analytics

[IngridT1]

For your more general question, @stoobie, we think it would be a good idea to add more guidance about headings in either the Supplementary Style Guide (SSG) or the Mod Docs guide (https://github.com/redhat-documentation/modular-docs).

We do have an internal e-learning about headings and titles, and we could pick the most important advice from that e-learning and add it to one of those two guides--probably the SSG. We're still discussing.

[stoobie]

@IngridT1
That was indeed my intent when I suggested this.

[bergerhoffer]

Outcome from the June 5 meeting: it could potentially be worthwhile to take some of the material covered in the learning course and state them in the SSG. Not sure yet if anyone has bandwidth to take this on, but @IngridT1 and @bredamc might see if they have any time come July or so.

[stoobie]

If someone can send me the source material, I might have time to create a pr.

…

On Tue, Jun 18, 2024, 21:41 Andrea Hoffer ***@***.***> wrote: Outcome from the June 5 meeting: it could potentially be worthwhile to take some of the material covered in the learning course and state them in the SSG. Not sure yet if anyone has bandwidth to take this on, but @IngridT1 <https://github.com/IngridT1> and @bredamc <https://github.com/bredamc> might see if they have any time come July or so. — Reply to this email directly, view it on GitHub <#469 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AJLVVLOJSOFYKZTTBXASWU3ZIB5OPAVCNFSM6AAAAABGCFTORKVHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZDCNZWG4ZTKNRUHA> . You are receiving this because you were mentioned.Message ID: <redhat-documentation/supplementary-style-guide/issues/469/2176735648@ github.com>