chore(website): streamlined Getting Started docs (typescript-eslint#5248

)

* chore(website): streamlined Getting Started docs

* Fix: check-spelling; lint-markdown

* Fixed remaining typed-linting issues

* Apply suggestions from code review

Co-authored-by: Brad Zacher <brad.zacher@gmail.com>

* TSLINT_RULE_ALTERNATIVES.md

* Code case

* Remove prettier-ignore

Co-authored-by: Brad Zacher <brad.zacher@gmail.com>

.cspell.json

@@ -8,7 +8,7 @@
     "**/*.{json,snap}",
     "**/**/CHANGELOG.md",
     "**/**/CONTRIBUTORS.md",
-    "**/**/ROADMAP.md",
+    "**/**/TSLINT_RULE_ALTERNATIVES.md",
     "**/coverage/**",
     "**/dist/**",
     "**/fixtures/**",
@@ -88,6 +88,7 @@
     "preact",
     "Premade",
     "prettier's",
+    "Quickstart",
     "recurse",
     "redeclaration",
     "redeclarations",

_redirects

@@ -0,0 +1,4 @@
+/docs/linting /docs
+/docs/linting/type-linting /docs/linting/typed-linting
+/docs/linting/monorepo /docs/linting/typed-linting/monorepos
+/docs/linting/tslint /docs/linting/troubleshooting/tslint

docs/README.md

@@ -1,13 +1,79 @@
 ---
+id: getting-started
 title: Getting Started
-sidebar_label: Getting Started
 slug: /
 ---
 
-These docs will give you a quick overview of the project and all of its pieces, as well as provide guides to help you get set up.
+## Quickstart
 
-The docs are broken down into the following categories:
+These steps will get you running ESLint with our recommended rules on your TypeScript code as quickly as possible.
 
-- [I want to lint my TypeScript codebase.](./linting/README.md)
+### Step 1: Installation
 
-- [I want to develop an ESLint plugin in TypeScript.](./development/CUSTOM_RULES.md)
+First, install the required packages for [ESLint](https://eslint.io), [TypeScript](https://typescriptlang.org), and this plugin:
+
+```bash npm2yarn
+npm install --save-dev @typescript-eslint/parser @typescript-eslint/eslint-plugin eslint typescript
+```
+
+### Step 2: Configuration
+
+Next, create a `.eslintrc.cjs` config file in the root of your project, and populate it with the following:
+
+```js title=".eslintrc.cjs"
+module.exports = {
+  extends: ['eslint:recommended', 'plugin:@typescript-eslint/recommended'],
+  parser: '@typescript-eslint/parser',
+  plugins: ['@typescript-eslint'],
+  root: true,
+};
+```
+
+:::info
+If your project doesn't use ESM, naming the file as `.eslintrc.js` is fine. See [ESLint's Configuration Files docs](https://eslint.org/docs/user-guide/configuring/configuration-files) for more info.
+:::
+
+### Step 3: Running ESLint
+
+Open a terminal to the root of your project and run the following command:
+
+<Tabs groupId="npm2yarn">
+<TabItem value="npm">
+
+```bash
+npx eslint .
+```
+
+</TabItem>
+<TabItem value="Yarn">
+
+```bash
+yarn eslint .
+```
+
+</TabItem>
+</Tabs>
+
+ESLint will lint all TypeScript compatible files within the current folder, and will output the results to your terminal.
+
+## Details
+
+- You can read more about configuring ESLint [in their documentation on configuration](https://eslint.org/docs/user-guide/configuring).
+- You can read more about the rules provided by ESLint [in their documentation on their rules](https://eslint.org/docs/rules/).
+- You can read more about the rules provided by typescript-eslint in [our rules documentation](/rules).
+
+### Configuration Values
+
+- `parser: '@typescript-eslint/parser'` tells ESLint to use the [`@typescript-eslint/parser`](https://github.com/typescript-eslint/typescript-eslint/tree/main/packages/parser) package you installed to parse your source files.
+  - This is required, or else ESLint will throw errors as it tries to parse TypeScript code as if it were regular JavaScript.
+- `plugins: ['@typescript-eslint']` tells ESLint to load the [`@typescript-eslint/eslint-plugin`](https://github.com/typescript-eslint/typescript-eslint/tree/main/packages/eslint-plugin)) package as a plugin.
+  - This allows you to use typescript-eslint's rules within your codebase.
+- `extends: [ ... ]` tells ESLint that your config extends the given configurations.
+  - `eslint:recommended` is ESLint's inbuilt "recommended" config - it turns on a small, sensible set of rules which lint for well-known best-practices.
+  - `plugin:@typescript-eslint/recommended` is our "recommended" config - it's just like `eslint:recommended`, except it only turns on rules from our TypeScript-specific plugin.
+
+## Next Steps
+
+We provide a plethora of powerful rules that utilize the power of TypeScript's type information. [Visit the next page for a setup guide](./linting/TYPED_LINTING.md 'Visit the next page for a typed rules setup guide').
+
+If you're having problems getting this working, please have a look at our [Troubleshooting & FAQs](./linting/TROUBLESHOOTING.md).

docs/development/architecture/PACKAGES.md

@@ -66,7 +66,7 @@ Any custom rules you write generally will be as well.
 [`@typescript-eslint/eslint-plugin-tslint`] is a separate ESLint plugin that allows running TSLint rules within ESLint to help you migrate from TSLint to ESLint.
 
 :::caution
-**TSLint is deprecated.** It is in your best interest to migrate off it entirely. See [Linting > TSLint](../../linting/TSLINT.md).
+**TSLint is deprecated.** It is in your best interest to migrate off it. See [Linting > Troubleshooting & FAQs > What About TSLint?](../../linting/troubleshooting/TSLINT.md).
 :::
 
 [`@typescript-eslint/eslint-plugin-tslint`]: https://github.com/typescript-eslint/typescript-eslint/tree/main/packages/eslint-plugin-tslint

docs/linting/CONFIGS.md → docs/linting/CONFIGURATIONS.md

@@ -1,16 +1,21 @@
 ---
 id: configs
-sidebar_label: Configurations
 title: Configurations
 ---
 
+[ESLint shareable configurations](https://eslint.org/docs/latest/developer-guide/shareable-configs) exist to provide a comprehensive base config for you, with the intention that you add the config and it gives you an opinionated setup.
+
 ## Built-In Configurations
 
 `@typescript-eslint/eslint-plugin` includes built-in configurations you can extend from to pull in the recommended starting rules.
 
 With the exception of `strict`, all configurations are considered "stable".
 Rule additions and removals are treated as breaking changes and will only be done in major version bumps.
 
+:::note
+We recommend most packages extend from [`recommended-requiring-type-checking`](#recommended-requiring-type-checking) (which requires [typed linting](./TYPED_LINTING.md)).
+:::
+
 ### `eslint-recommended`
 
 This ruleset is meant to be used after extending `eslint:recommended`.
@@ -60,7 +65,7 @@ Rules in this configuration are similarly useful to those in `recommended`.
 
 :::tip
 We recommend all TypeScript projects extend from this configuration, with the caveat that rules using type information take longer to run.
-See [Linting with Type Information](/docs/linting/type-linting) for more details.
+See [Linting with Type Information](/docs/linting/typed-linting) for more details.
 :::
 
 ### `strict`
@@ -89,4 +94,29 @@ See [ESLint's Configuring Rules docs](https://eslint.org/docs/user-guide/configu
 
 ### Suggesting Configuration Changes
 
-If you feel strongly that a specific rule should (or should not) be one of these configurations, please feel free to [file an issue](https://github.com/typescript-eslint/typescript-eslint/issues/new/choose) along with a **detailed** argument explaining your reasoning.
+If you feel strongly that a specific rule should (or should not) be one of these configurations, please [file an issue](https://github.com/typescript-eslint/typescript-eslint/issues/new?assignees=&labels=package%3A+eslint-plugin%2Cpreset+config+change%2Ctriage&template=09-config-change.yaml&title=Configs%3A+%3Ca+short+description+of+my+proposal%3E) along with a **detailed** argument explaining your reasoning.
+
+## Prettier
+
+If you use [`prettier`](https://www.npmjs.com/package/prettier), there is also a helpful config to help ensure ESLint doesn't report on formatting issues that prettier will fix: [`eslint-config-prettier`](https://www.npmjs.com/package/eslint-config-prettier).
+
+Using this config by adding it to the end of your `extends`:
+
+```js title=".eslintrc.js"
+module.exports = {
+  root: true,
+  parser: '@typescript-eslint/parser',
+  plugins: ['@typescript-eslint'],
+  extends: [
+    'eslint:recommended',
+    'plugin:@typescript-eslint/recommended',
+    // Add this line
+    'prettier',
+  ],
+};
+```
+
+:::warning
+**We strongly recommend you use Prettier or an equivalent**, not ESLint formatting rules.
+See [this issue](https://github.com/typescript-eslint/typescript-eslint/issues/4907 'Issue: Docs: Add our opinion on delegating stylistic issues to a tool such as Prettier #4907') for more information.
+:::