Make description of _GROUP_ID more obvious

[asmorodskyi]

No description provided.

[github-actions]

Great PR! Please pay attention to the following items before merging:

Files matching docs/*.asciidoc:

• Consider generating documentation locally to verify it is rendered correctly. See https://open.qa/docs/#_making_documentation_changes

This is an automatically generated QA checklist based on modified files.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 99.22%. Comparing base (92286c8) to head (342aca0).
⚠️ Report is 50 commits behind head on master.

Additional details and impacted files

@@           Coverage Diff           @@
##           master    #6683   +/-   ##
=======================================
  Coverage   99.21%   99.22%           
=======================================
  Files         398      398           
  Lines       40872    40872           
=======================================
+ Hits        40553    40554    +1     
+ Misses        319      318    -1     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[Martchus]

I like the current descriptions better.

[Martchus]

This is now not a full sentence anymore.

Suggested change

	_GROUP:: Limiting lookup for job templates only to group with matching name.
	_GROUP:: Limits the lookup for job templates to only the group with matching name.

I must say that I still find the previous/current description the best.

[asmorodskyi]

Both sentences are grammatically correct, but they have slightly different meanings and common usage.

When you say:

"Limit the lookup for job templates to groups with a matching name."

The word "groups" is being used in a general sense. You're talking about the class of all groups that have this characteristic (a matching name). This is the more common and natural way to phrase a general rule or instruction.

When you add "the":

"Limit the lookup for job templates to the groups with a matching name."

You are referring to a specific, previously-mentioned, or well-understood set of groups. It implies that there is a particular collection of groups you are already talking about.

In this context, since the sentence is likely a general statement of a rule or a system's behavior, omitting "the" is more appropriate. It makes the sentence a clear, concise, and universal instruction, not one that depends on a specific, already-identified set of groups.

I would say we should not use "the" in that case so if it is ok for you I will change that to Limits the lookup for job templates to only group with matching name. basically your version but w/o "the" before groups

[Martchus]

The sentence "Limits the lookup for job templates to only group with matching name." is not identical to the sentence "Limit the lookup for job templates to groups with a matching name.". Only the latter is grammatically correct (according to the AI response which is also in-line with my understanding). The latter uses "groups" (plural) instead of "group" singular.
(EDIT: Technically the first sentence is also correct if you think of "group" as a verb. However, then the sentence is not conveying the meaning it is supposed to convey. Because of this ambiguity I suggested the change in the first place. And I still find the version before this change the easiest to make sense of.)

So you may change it to "Limit the lookup for job templates to groups with a matching name.". However, I chose "the group" (article and singular) in my suggestion because there will only be one group with a matching name and we specify this name here. So the setting refers to a specific group. The AI also says that one should use "the" when referring to a specific group. (The AI thinks in terms of multiple groups here but it cannot know that we only specify and refer to a single group here.) So I still think my initial suggestion is best.

[Martchus]

Again, not a full sentence. And isn't it good to refer to _GROUP as the current description does? This makes it immediately clear that both parameters do the same thing - the group is just specified in a different way.

[asmorodskyi]

well it is hard to argue because it is personal thing but for me it was not clear what exactly is "the same"

[Martchus]

Sorry, but I'm not sure how that cannot be clear :-)

[kalikiana]

"Same as _GROUP" means "Behaves the same as _GROUP"... maybe "Limit the lookup by group ID, as an alternative to using _GROUP" would be more explicit?

[asmorodskyi]

I like the current descriptions better.

can you elaborate ? it is hard to argue with this statement .
My main concern that description of one variable should not force you to read description of another no matter that they are "neighbours" in the text

[Martchus]

My main concern that description of one variable should not force you to read description of another no matter that they are "neighbours" in the text

I disagree. There's no harm in the reference when it just refers to the previous line. When one is reading from top to bottom this way repetition is avoided. When one reads the last variable first they just have to look one line above and then maybe even realize that this is the variable they were actually looking for.