Docs: Make rule descriptions more consistent

[scriptdaemon]

For each rule doc, I made the title consistent with the description in the README.md file. Since I also made some grammar changes for better consistency between rules, I want to make sure those changes are acceptable as well.

[mention-bot]

By analyzing the blame information on this pull request, we identified @alberto, @kaicataldo and @onurtemizkan to be potential reviewers

[eslintbot]

LGTM

[kaicataldo]

Is there an issue open for this? I can make more specific comments later (on my commute to work right now), but I feel like some of these changes make what the respective rule enforces less clear.

I'm all for consistency as long as it improves clarity though :)

[kaicataldo]

Sorry, let me actually rephrase my question: What's the motivation behind this change? I've personally never felt like inconsistencies in the rule descriptions were problem.

From my quick scan it looked to me like some of changes sacrifice clarity and detail in the descriptions for more consistent word choice, which is not a good trade off in my opinion.

Never mind, I understand now. I totally agree that having consistency between the readme and rule docs would be great.

[kaicataldo]

I personally prefer the previous version - this seems less helpful to me

[kaicataldo]

@scriptdaemon Okay, now I'm at a computer! I should have said this earlier - thanks for the PR :)

Generally, we like for there to be an accepted issue so we can hammer out the details before any work is done and ensure it's a change we want to make (as well as making sure people aren't putting time into something that may or may not be used).

I love the idea of your PR - we should definitely have parity between the rule descriptions in the readme and the rule docs themselves. You also bring up some interesting inconsistencies where I'm not sure what the right way forward is (the "one true comma style" one is a good example). Let's see what the rest of the team has to say.

[nzakas]

@kaicataldo doc changes don't require issues so long as the purpose is obvious.

I think we have to be careful not to undo @pedrottimark's work on this, so let's get his input before proceeding.

[kaicataldo]

@nzakas Ah okay, thanks for clarifying 👍

[pedrottimark]

Super effort to make rule descriptions more clear and consistent!

Here are suggestions how to move forward:

• In this PR, let’s review changes to README.md but not copy changes the rule docs, so we avoid merge conflicts with work-in-progress on the example and fixable sentences, okay? P.S. @scriptdaemon could you take a look at Docs: WIP Guidelines for rule pages #5446 and tell me if you want a share of that task?
• When the time comes (soon) to edit rule docs, let’s make their headings similar in form to README.md name-of-rule: description of rule as pictured in Improve information architecture of site archive-website#186 (comment)
• After Docs: Consistent wording in rules README #5630 and before reviewing these changes, here is a list of 8 verbs I found in rule descriptions: disallow, encourage, enforce, ensure, require, restrict, specify, treat…as if (only 1 occurrence). Can the team express preferences to reduce the verbs to the minimum number of “use cases” so rules which have similar effect have same verb and rules which have different verb have different effect.
• After this PR, what does the team think about a one-time change in README.md from lists to tables, as pictured in Improve information architecture of site archive-website#186 (comment) and Improve information architecture of site archive-website#186 (comment)?

[pedrottimark]

Concerning the verbs, in a first look at the patterns for describing options in rule docs, the contrasting verbs seem to be enforces and disallows to describe positive versus negative constraints.

[ilyavolodin]

I would replace encourage with enforce or require. Same with ensure. Remove specify and treat. So you left with disallow, enforce/require and restrict.
I'm perfectly fine with switching README.md to the table as displayed in your examples. I think it will be a bit easier to consume from the user perspective.

[scriptdaemon]

@kaicataldo In the PR for max-statements-per-line I was asked to keep the title of the rule doc and the description of the rule in the README.md consistent, so I wanted to apply that consistency across the board. I'm definitely glad you have concerns, as wording can be very subjective, and I agree with the ones you have so far.

@pedrottimark Thank you. I knew you were working on doc updates as well so I was hoping to have your input (I suppose I could have just pinged you myself =P). For each of your bullet points:

• Makes sense to me. I'll update this commit when time permits so that it only involves updating the language of the descriptions in the README.md. Also, I wouldn't mind helping out with Docs: WIP Guidelines for rule pages #5446 at all.
• Given how much I was able to reduce in the PR as it stands right now, I agree with @ilyavolodin. I think I tried too hard to reduce in some rules to the point where it may have made the wording a little awkward, so opening it back up to allow require and restrict would be better.
• 👍 for tables.

[pedrottimark]

@scriptdaemon What about this pattern to replace some “enforce or disallow” pairs with enforce?

• array-bracket-spacing: enforce spacing style inside array brackets (fixable)
• block-spacing: enforce spacing style inside single-line blocks (fixable)
• brace-style: enforce brace style for blocks
• camelcase: enforce camel case style for names
• comma-spacing: enforce spacing style before and after commas (fixable)

As long as X style is not too vague.

[scriptdaemon]

@pedrottimark I like that. That helps keep some of the rules' descriptions more succinct,

[scriptdaemon]

@pedrottimark Now that I've gotten down to the stylistic rules in the README, I took your idea and made some adjustments that I think read a bit easier (I'm not against changing them back if you disagree). Let me know what you think.

• array-bracket-spacing: enforce consistent spacing inside array brackets (fixable)
• block-spacing: enforce consistent spacing inside single-line blocks (fixable)
• brace-style: enforce consistent brace style for blocks
• camelcase: enforce camelcase naming convention
• comma-spacing: enforce consistent spacing before and after commas (fixable)

EDIT: I amended the commit to include my current changes. Please look over my wording to see if you agree or think anything should be changed.

[pedrottimark]

enforce consistent spacing inside computed property brackets (fixable)

[pedrottimark]

declared either together or separately

You might think of an even clearer word to communicate the contrast.

[scriptdaemon]

This one actually took me the longest to figure out a wording that wasn't completely awkward. I like your suggestion better.

[pedrottimark]

@scriptdaemon 👍 👍 to your improved wording. You are brave to work on 227 rule descriptions, sir.

Commented on Stylistic Issues. If it is helpful, can look at other sections.

[scriptdaemon]

@pedrottimark Thank you for the feedback. I'll go through your changes, then apply whatever changes necessary to the rules in the other sections to remain consistent.

I raised a few questions in your PR (e.g. whether we should use plural vs singular), and depending the direction you think we should take I'll factor those changes into the rule descriptions as well.

[scriptdaemon]

@pedrottimark All changes as discussed so far have been implemented.

[pedrottimark]

disallow unnecessary boolean casts

The original description had 2 issues:

• “boolean cast” refers to either !! or Boolean()
• “in a boolean context” was trying to communicate something similar to “unnecessary” in no-extra-parens

[pedrottimark]

Added 4 line comments where there was an inconsistency between original description and current rule options, plus 1 nitpick for stray period.

Other than those, LGTM

@scriptdaemon You reached beyond “low-hanging fruit” here. I had a gut instinct when you wrote that.

[scriptdaemon]

@pedrottimark Done.

The progress on this is looking good. Now just waiting on other feedback.

Once this is merged, when do we want to update the doc titles for each rule?

[pedrottimark]

@scriptdaemon Will probably merge on Monday because descriptions are on critical path for #5417

Let’s update the main headings in docs as part of the task to develop and implement guidelines for example sentences and option descriptions:

• I will (1) update guidelines for examples according to Update: add allowEmptyCatch option to no-empty (fixes #5800) #5807 (comment) and (2) add options in Docs: WIP Guidelines for rule pages #5446 and (3) update missing examples in Docs: Missing examples in rule pages #5529 and (4) start at the beginning of the index to bring already-edited docs up to rising level of consistency and add missing examples.
• Would you like to start where I left off in Docs: Distinguish examples in rules under Stylistic Issues part 1 #5802 (another PR worth reading is Docs: Distinguish examples in rules under Node.js and CommonJS #5598 although my prediction about number of PR and target date makes me laugh at myself :) I suggest batches of 10 to 15 adjacent rules under same heading in rules index. Please add comments to Docs: WIP Guidelines for rule pages #5446 with any specific sentences that might be useful in future guidelines doc for contributors and maintainers. Also any adjustments to guidelines which arise from discussions in the pull requests. And add to Docs: Missing examples in rule pages #5529 any missing examples, taking into account it is okay for allow/exceptions options to have only additional correct code.

[scriptdaemon]

@pedrottimark That all sounds good to me.

Do you have a collected list of the ones you've already done? If you haven't done the rule under the "strict" category yet, I can quickly do that tomorrow to see if I have in mind the correct way you want these done.

[pedrottimark]

@scriptdaemon Great minds think alike. I started with Variables because it was a small section, but then worked from the beginning through the first 10 in Stylistic Issues. So there are no gaps.

Because I included strict in #5596 the next best thing is try global-strict under Removed

By the way, I meant 10 to 15 as an upper bound for the sake of the reviewers and to reduce chance of merge conflicts. Smaller batches are fine.

[scriptdaemon]

@pedrottimark Ah, gotcha.

The reason I mentioned the one under strict was that it quick since that category only contains one rule, not because I only intended to start with one rule. I can do the next 10-15 from where you left off no problem since you already did it.