Docs: Consistent wording in rules README

[alberto]

No description provided.

[mention-bot]

By analyzing the blame information on this pull request, we identified @btmills, @kentor and @gcochard to be potential reviewers

[eslintbot]

LGTM

[ilyavolodin]

Nice! The only thing, we should also modify rule's pages with the same changes.

[alberto]

Yeah, I originally intended to put this first for approval and ask about also changing the rules, but then I forgot 😅

[pedrottimark]

Super! You reduced 20 description prefixes to 8 verbs: disallow, encourage, enforce, ensure, require, restrict, specify, treat…as if

As suggested in #5630 (comment), how about a common pattern of rule-name: rule description

That is:

• in the rule list, s/ - /: /
• in rule pages, move the rule-name from the end to the beginning followed by colon instead of enclosed in parentheses; use the description from the list in most cases, therefore reduce capitalization from Title Caps to phrase capitalization; omit the (recommended) and (fixable) suffixes

[alberto]

Do you think the list of verbs could be further reduced?

[alberto]

@pedrottimark where do you want to remove the suffixes from? I did a quick search and only found (recommended) and (fixable) in the README.

For the other proposed changes, can someone from @eslint/eslint-team confirm this is desired before I go and change all the rules docs?

[pedrottimark]

@alberto what I meant is that the rule descriptions in the list seem stronger than in the rule pages when there is a difference, but if we copy that text, we don’t want to bring (recommended) or (fixable) into the rule pages. Does that make sense?

To your previous #5630 (comment):
Yes, a good goal is to reduce the verbs so they correspond to use cases for rules.
By the way, unclear or inconsistentent noun phrases in rule descriptions have been on the back burner of my brain.

[kaicataldo]

Just for some context, currently (recommended) and (fixable) are used to add the icons on the rules list page: eslint/archive-website#180

Makes sense to me to not necessarily bring those labels into the rule page itself

[alberto]

@pedrottimark @kaicataldo thanks, now I see what you meant

[pedrottimark]

May I suggest wait on updates to the rule pages to avoid merge conflicts with the updates to sentences preceding example code?

You might want to look at pictures of some previously suggested, but not yet decided, improvements to the icons in rules list and rule pages:

• Improve information architecture of site archive-website#186 (comment)
• Improve information architecture of site archive-website#186 (comment)
• Improve information architecture of site archive-website#186 (comment)

They are independent of wording improvements, but the whole is more than the sum of the parts ;)

[alberto]

Ok, so I updated the README with the proposed changes for now. We can later create another PR for the rules.

[nzakas]

What's the verdict on merging this? Wait?

[pedrottimark]

This is a great step forward, which seems well worth merging.

Because it is so much easier to see potential improvements in the context of the entire list, how about leaving open the opportunity to iterate on it a few times before updating the rule pages? Their headings have been inconsistent with the list for a while now, from previous rounds of editing.

Is it time to change from lists to tables with check mark and wrench icon at the left? I could make a follow-up pull request soon. It depends on just one more replace rule in the doc.html layout file at eslint.github.io

[nzakas]

@pedrottimark I don't care how many times we iterate as long as things are improving. My only concern is that the longer these doc change PRs sit, the more potential for problems as documentation is being updated and added. I just want to keep things moving.

[pedrottimark]

👍