Description
Before You File a Documentation Request Please Confirm You Have Done The Following...
- I have looked for existing open or closed documentation requests that match my proposal.
- I have read the FAQ and my problem is not listed.
Suggested Changes
The rules reference lists all of the rules. It's the first place that someone goes to when they want to start looking through all of the rules that typescript-eslint offers.
Right now, they are separated into 2 categories: Supported Rules & Extension Rules.
However, this layout does not capture which rules are formatting rules (which are greatly discouraged from being used) and it does not capture which rules are deprecated (which obviously shouldn't be used). In other words, the "bad" rules are lumped in together with everything else, which makes the experience painful as an end-user who is going through the list to find out which ones they want to enable for their codebase.
On the left sidebar, there is a "Formatting Rules" and "Deprecated Rules" section, but this is pretty obscure and hard to miss, especially because they are all the way at the bottom behind a huge list of rules. Furthermore, the fact that these sidebars exist isn't represented on the main rules page. So I motion that these sidebar categories are completely deleted and the categorization is merged into the main rules page in some way.
First, I'd mention that we might want to take inspiration from the ESLint rules page, which delineates rules into four categories:
- Possible Problems
- Suggestions
- Layout & Formatting
- Deprecated
(I'm not counting the "Removed" category here.)
So, we could fix this problem in a few different ways. I think one way is to replicate the ESLint rule layout, such that the ordering of rules on the page would look something like this:
- Possible Problems
- Possible Problems (Main Rules)
- Possible Problems (ESLint Extension Rules)
- Suggestions
- Suggestions (Main Rules)
- Suggestions (ESLint Extension Rules)
- Layout & Formatting
- Layout & Formatting (Main Rules)
- Layout & Formatting (ESLint Extension Rules)
- Deprecated
- Deprecated (Main Rules)
- Deprecated (ESLint Extension Rules)
At the end of the day, the problem we are looking to solve is that users can go through the menu of rules without tripping over "bad" rules. Or, they can easily see from a glance which rules are formatting rules when browsing the master rule list.