Soften the advice for "check"

[julian-cable]

Current entry:

check
Avoid. Use "verify", "ensure", or "read", depending on the context.

Maybe:
Avoid if an alternative verb such as "verify", "ensure", or "read" fits in the context.
Instead of "check this site", use "Refer to www.somewhere.com for more information."

[rclee33]

Thanks for opening this issue! I like the new sentence about references. This entry is a good place to add a reminder about "refer to".

I suggest providing a greater range of alternatives, putting them in alphabetical order, and replacing "read" with "review". And let's also add the part of speech, for clarity.

For example:
v. Avoid if a more precise verb fits the context, such as "ensure", "examine", "inspect", "review", or "verify".

My only other suggestion is to add a brief rationale about why we avoid "check". In fact, the reasoning isn't clear to me. Is it because the verb "check" has so many definitions? When guidance leaves room for flexibility, it's useful to include the rationale so that folks can make informed choices about whether to use it or not.

Just noting that we'll also need to update the corresponding Vale rule/text, if we make this change.

[daobrien]

If you look at version 6.1 of the style guide you'll see all of that info. It was removed in 6.2.

[rclee33]

Hm, I see the same entry in 6.1 as in 6.2.

[daobrien]

There's more in 6.1. Do a search for "check this site". That's what I meant got removed, not the entry for "check" in the usage section.

[julian-cable]

Yes, I removed the entry for "check this site" per the decision communicated in #532.

I do think we should still have an entry for "check", but rather than having a blanket ban ("Avoid"), to soften the guidance to explain when it might or might not be suitable to use.

[rclee33]

@daobrien Oh, I see -- thank you.

@julian-cable Yes, I agree: keep an entry for "check" and soften the blanket ban (with some explanation).

[rclee33]

Adding an example from the wild where using "checks" would be appropriate - when discussing the fsck tool.

RH342 (CH08s04 GE) HLD section objective: “Check a file system and repair file system corruption.”

• The tool that is used in this section (fsck) uses “check” as the tool’s abbreviation and throughout the documentation to describe the tool’s functionality: “check and repair a Linux file system” https://linux.die.net/man/8/fsck
• Note: The original objective that used "checks" was updated to avoid "checks", per the current guidance.

[rclee33]

Another example: "check" (and "checking") are currently used in the scaffolding template for CH00 content: content/introduction/perform/perform.adoc:

• "A quiz is typically used when checking knowledge-based learning, or when a hands-on activity is impractical for some other reason."
• "An end-of-chapter lab is a gradable hands-on activity to help you to check your learning."
• "The start action verifies the required resources to begin an exercise. It might include configuring settings, creating resources, checking prerequisite services, and verifying necessary outcomes from previous exercises."

[rclee33]

I opened a Vale issue so that our guidance across guides/tools can stay aligned: https://github.com/RedHatTraining/vale-styles/issues/364

[daobrien]

Another example: "check" (and "checking") are currently used in the scaffolding template for CH00 content: content/introduction/perform/perform.adoc:

• "A quiz is typically used when checking knowledge-based learning, or when a hands-on activity is impractical for some other reason."
• "An end-of-chapter lab is a gradable hands-on activity to help you to check your learning."
• "The start action verifies the required resources to begin an exercise. It might include configuring settings, creating resources, checking prerequisite services, and verifying necessary outcomes from previous exercises."

You'll probably find that nobody has run Vale over the scaffolding template yet, although I have asked a couple of times. Being in the template doesn't mean it's valid (although it probably should). Each of those examples could easily be rephrased to avoid "check".

[rclee33]

I'm still not sure why we're avoiding "check". What's the reasoning?

[daobrien]

I'm still not sure why we're avoiding "check". What's the reasoning?

The original reasoning (from when I don't know) was that "check" has lots of different meanings.

See #532

In a Word Nerds discussion we decided to just remove the guidance altogether, and this is why I started asking why it was being resurrected. I brought this up in https://redhat-internal.slack.com/archives/C06DRCC1NDS/p1710832958740089

There was never a blanket ban on "check". We rarely implement bans unless it's a Legal or Brand issue.

[rclee33]

Got it, thank you!