docs: reorganise release/version docs (#7033)

* docs: reorganise release/version docs

* Apply suggestions from code review

Co-authored-by: Joshua Chen <sidachen2003@gmail.com>

* more docs updates

* correct casing

---------

Co-authored-by: Joshua Chen <sidachen2003@gmail.com>

docs/Developers.mdx

@@ -0,0 +1,10 @@
+---
+id: developers
+title: Developers
+---
+
+These are the developer guides to working with the typescript-eslint tooling.
+It's intended for use by third-parties who want to use our tools to build great things.
+
+> If you're reading this as a new developer: welcome to the community!
+> We're happy to have you! ❤️‍🔥

docs/Getting_Started.mdx

@@ -58,9 +58,9 @@ ESLint will lint all TypeScript compatible files within the current folder, and
 
 ## Details
 
-- `parser: '@typescript-eslint/parser'` tells ESLint to use the [`@typescript-eslint/parser`](./architecture/Parser.mdx) package you installed to parse your source files.
+- `parser: '@typescript-eslint/parser'` tells ESLint to use the [`@typescript-eslint/parser`](./packages/Parser.mdx) 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`](./architecture/ESLint_Plugin.mdx) package as a plugin.
+- `plugins: ['@typescript-eslint']` tells ESLint to load the [`@typescript-eslint/eslint-plugin`](./packages/ESLint_Plugin.mdx) 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.

docs/Maintenance.mdx

@@ -8,5 +8,7 @@ This is the maintainers guide to working on typescript-eslint.
 It's intended for use by contributors who have been given access to at least triage issues and pull requests.
 We keep it in the open for visibility into our processes.
 
-> If you're reading this as a new maintainer: welcome!
-> We're happy to have you! ❤️‍🔥
+:::info Welcome!
+If you're reading this as a new maintainer: welcome!
+We're happy to have you! ❤️‍🔥
+:::

docs/Packages.mdx

@@ -0,0 +1,17 @@
+---
+id: packages
+title: Packages
+---
+
+The `@typescript-eslint/*` packages are all stored in [our GitHub monorepo](https://github.com/typescript-eslint/typescript-eslint).
+The monorepo is built with [Lerna](https://lerna.js.org) and [Nx](https://nx.dev).
+
+Each page in this section corresponds to a package we intentionally expose to users.
+They are:
+
+- [`@typescript-eslint/eslint-plugin`](./packages/ESLint_Plugin.mdx): An ESLint plugin which provides lint rules for TypeScript codebases.
+- [`@typescript-eslint/eslint-plugin-tslint`](./packages/ESLint_Plugin_TSLint.mdx): An ESLint plugin that allows running TSLint rules within ESLint to help you migrate from TSLint to ESLint.
+- [`@typescript-eslint/parser`](./packages/Parser.mdx): An ESLint parser which allows for ESLint to lint TypeScript source code.
+- [`@typescript-eslint/scope-manager`](./packages/Scope_Manager.mdx): A fork of [`eslint-scope`](https://github.com/eslint/eslint-scope), enhanced to support TypeScript functionality.
+- [`@typescript-eslint/typescript-estree`](./packages/TypeScript_ESTree.mdx): The underlying code used by [`@typescript-eslint/parser`](./packages/Parser.mdx) that converts TypeScript source code into an [ESTree](https://github.com/estree/estree)-compatible form.
+- [`@typescript-eslint/utils`](./packages/Utils.mdx): Utilities for working with TypeScript + ESLint together.

docs/Users.mdx

@@ -0,0 +1,12 @@
+---
+id: users
+title: Users
+---
+
+These are the user guides to consuming the typescript-eslint tooling.
+It's intended for users who want to consume our tools.
+
+:::info Welcome!
+If you're reading this as a new user: welcome to the community!
+We're happy to have you! ❤️‍🔥
+:::

docs/contributing/Discussions.md → docs/contributing/Discussions.mdx

@@ -23,5 +23,5 @@ We can always move an issue to a discussion if it becomes unexpectedly deep.
 
 :::caution
 Please don't use Discussions as a support forum.
-See [Issues > Questions and Support Requests](./Issues.mdx#questions-and-support-requests).
+See [Contributing > Issues > Questions and Support Requests](./Issues.mdx#questions-and-support-requests).
 :::

docs/contributing/Local_Development.mdx

@@ -32,7 +32,7 @@ For example, if you make a change within `scope-manager` and want to use it in `
 The following checks are all run on pull requests automatically.
 You can also perform them locally.
 
-> See [Contributing > Pull Requests](../Contributing.mdx#raising-a-pr) for more information on pull requests.
+> See [Contributing > Pull Requests](./Pull_Requests.mdx) for more information on pull requests.
 
 ### Formatting
 

docs/Custom_Rules.mdx → docs/developers/Custom_Rules.mdx

@@ -1,12 +1,12 @@
 ---
 id: custom-rules
-sidebar_label: Custom Rules
+sidebar_label: Building Custom Rules
 title: Custom Rules
 ---
 
 :::important
 This page describes how to write your own custom ESLint rules using typescript-eslint.
-You should be familiar with [ESLint's developer guide](https://eslint.org/docs/developer-guide) and [ASTs](https://typescript-eslint.io/blog/asts-and-typescript-eslint) before writing custom rules.
+You should be familiar with [ESLint's developer guide](https://eslint.org/docs/developer-guide) and [ASTs](/blog/asts-and-typescript-eslint) before writing custom rules.
 :::
 
 As long as you are using `@typescript-eslint/parser` as the `parser` in your ESLint configuration, custom ESLint rules generally work the same way for JavaScript and TypeScript code.
@@ -18,7 +18,7 @@ The main three changes to custom rules writing are:
 
 ## Utils Package
 
-The [`@typescript-eslint/utils`](./architecture/Utils.mdx) package acts as a replacement package for `eslint` that exports all the same objects and types, but with typescript-eslint support.
+The [`@typescript-eslint/utils`](../packages/Utils.mdx) package acts as a replacement package for `eslint` that exports all the same objects and types, but with typescript-eslint support.
 It also exports common utility functions and constants most custom typescript-eslint rules tend to use.
 
 :::caution

docs/linting/Troubleshooting.mdx

@@ -7,7 +7,7 @@ title: Troubleshooting & FAQs
 
 This happens because TypeScript adds new features that ESLint doesn't know about.
 
-The first step is to [check our list of "extension" rules here](https://typescript-eslint.io/rules/#extension-rules).
+The first step is to [check our list of "extension" rules here](/rules/#extension-rules).
 An extension rule is a rule which extends the base ESLint rules to support TypeScript syntax.
 If you find it in there, give it a go to see if it works for you.
 You can configure it by disabling the base rule, and turning on the extension rule.
@@ -23,10 +23,10 @@ Here's an example with the `semi` rule:
 ```
 
 If you don't find an existing extension rule, or the extension rule doesn't work for your case, then you can go ahead and check our issues.
-[The contributing guide outlines the best way to raise an issue](https://github.com/typescript-eslint/typescript-eslint/blob/main/CONTRIBUTING.md#raising-issues).
+[The contributing guide outlines the best way to raise an issue](../contributing/Issues.mdx).
 
 > We release a new version our tooling every week.
-> _Please_ ensure that you [check our the latest list of "extension" rules](https://typescript-eslint.io/rules/#extension-rules) **_before_** filing an issue.
+> _Please_ ensure that you [check our the latest list of "extension" rules](/rules/#extension-rules) **_before_** filing an issue.
 
 ## I get errors telling me "ESLint was configured to run ... However, that TSConfig does not / none of those TSConfigs include this file"
 
@@ -171,7 +171,7 @@ See [#2041](https://github.com/typescript-eslint/typescript-eslint/issues/2041)
 ESLint core contains the rule [`no-restricted-syntax`](https://eslint.org/docs/rules/no-restricted-syntax).
 This generic rule allows you to specify a [selector](https://eslint.org/docs/developer-guide/selectors) for the code you want to ban, along with a custom error message.
 
-You can use an AST visualization tool such as [typescript-eslint playground](https://typescript-eslint.io/play#showAST=es) > _Options_ > _AST Explorer_ on its left sidebar by selecting _ESTree_ to help in figuring out the structure of the AST that you want to ban.
+You can use an AST visualization tool such as [typescript-eslint playground](/play#showAST=es) > _Options_ > _AST Explorer_ on its left sidebar by selecting _ESTree_ to help in figuring out the structure of the AST that you want to ban.
 
 For example, you can ban enums (or some variation of) using one of the following configs:
 
@@ -290,11 +290,11 @@ See [this issue comment](https://github.com/typescript-eslint/typescript-eslint/
 ### I get `no-unsafe-*` complaints for cross-file changes
 
 See [Changes to one file are not reflected in linting other files in my IDE](#changes-to-one-file-are-not-reflected-when-linting-other-files-in-my-ide).
-Rules such as [`no-unsafe-argument`](https://typescript-eslint.io/rules/no-unsafe-argument), [`no-unsafe-assignment`](https://typescript-eslint.io/rules/no-unsafe-assignment), and [`no-unsafe-call`](https://typescript-eslint.io/rules/no-unsafe-call) are often impacted.
+Rules such as [`no-unsafe-argument`](/rules/no-unsafe-argument), [`no-unsafe-assignment`](/rules/no-unsafe-assignment), and [`no-unsafe-call`](/rules/no-unsafe-call) are often impacted.
 
 ## My linting feels really slow
 
-If you think you're having issues with performance, see our [Performance Troubleshooting documentation](./troubleshooting/Performance.md).
+If you think you're having issues with performance, see our [Performance Troubleshooting documentation](./troubleshooting/Performance.mdx).
 
 ## Are TypeScript project references supported?
 

docs/linting/Typed_Linting.mdx

@@ -34,10 +34,10 @@ See [our TSConfig inclusion FAQ](./Troubleshooting.mdx#i-get-errors-telling-me-e
 
 In more detail:
 
-- `plugin:@typescript-eslint/recommended-requiring-type-checking` is another [recommended configuration](./CONFIGURATIONS.mdx) we provide. This one contains recommended rules that additionally require type information.
+- `plugin:@typescript-eslint/recommended-requiring-type-checking` is another [recommended configuration](./Configurations.mdx) we provide. This one contains recommended rules that additionally require type information.
 - `parserOptions.project` tells our parser how to find the TSConfig for each source file (`true` indicates to find the closest `tsconfig.json` for each source file)
   - If your project is a multi-package monorepo, see [our docs on configuring a monorepo](./typed-linting/Monorepos.mdx).
-- `parserOptions.tsconfigRootDir` tells our parser the absolute path of your project's root directory (see [Parser#tsconfigRootDir](../architecture/Parser.mdx#tsconfigRootDir)).
+- `parserOptions.tsconfigRootDir` tells our parser the absolute path of your project's root directory (see [Parser#tsconfigRootDir](../packages/Parser.mdx#tsconfigRootDir)).
 
 With that done, run the same lint command you ran before.
 You may see new rules reporting errors based on type information!

docs/linting/troubleshooting/TSLint.mdx

@@ -17,7 +17,7 @@ You can look at [the alternatives list](https://github.com/typescript-eslint/typ
 
 There is also the ultimate fallback option of using both linters together for a while during your transition if you
 absolutely have to by using TSLint _within_ ESLint.
-For this option, check out [`@typescript-eslint/eslint-plugin-tslint`](../../architecture/ESLint_Plugin_TSLint.mdx).
+For this option, check out [`@typescript-eslint/eslint-plugin-tslint`](../../packages/ESLint_Plugin_TSLint.mdx).
 
 ## Why Deprecate TSLint?
 

docs/maintenance/versioning/dependant-version-upgrades.mdx → docs/maintenance/Dependency_Version_Upgrades.mdx

@@ -1,6 +1,6 @@
 ---
-id: dependant-version-upgrades
-title: Dependant Version Upgrades
+id: dependency-version-upgrades
+title: Dependency Version Upgrades
 ---
 
 ## ESLint
@@ -21,7 +21,7 @@ Whenever you discover any new areas of work that are blocked by dropping an old
 1. Upgrade the root `package.json` `devDependency` to the latest ESLint
 1. Add the new major version to the explicit `peerDependency` versions
 1. Check [`eslint-visitor-keys`](https://www.npmjs.com/package/eslint-visitor-keys) for a new version to be upgraded to as well.
-1. Update [Versioning > ESLint](../Versioning.mdx#eslint)
+1. Update [Users > Dependency Versions > ESLint](../users/Dependency_Versions.mdx#eslint)
 
 ### Removing Support for an Old ESLint Version
 
@@ -32,7 +32,7 @@ Whenever you discover any new areas of work that are blocked by dropping an old
      - `/eslint.*5/i`
      - `/todo.*eslint.*5/i`
      - `/todo.*eslint/i`
-1. Update [Versioning > ESLint](../Versioning.mdx#eslint)
+1. Update [Users > Dependency Versions > ESLint](../users/Dependency_Versions.mdx#eslint)
 
 See [chore: drop support for ESLint v6](https://github.com/typescript-eslint/typescript-eslint/pull/5972) for reference.
 
@@ -88,8 +88,8 @@ We generally start the process of supporting a new TypeScript version just after
    - In the root `package.json`, change the `devDependency` on `typescript` to `~X.Y.3`
    - Rename and update `patches/typescript*` to the new TypeScript version
    - Any other changes made necessary due to changes in TypeScript between the RC version and stable version
-   - Update the supported version range in [Versioning](../Versioning.mdx)
-1. Update [Versioning > TypeScript](../Versioning.mdx#typescript)
+   - Update the supported version range in [Users > Dependency Versions](../users/Dependency_Versions.mdx)
+1. Update [Users > Dependency Versions > TypeScript](../users/Dependency_Versions.mdx#typescript)
 1. Send a PR that updates this documentation page to point to your newer issues and PRs
    - Also update any of these steps if you go with a different process
 
@@ -108,7 +108,7 @@ A single PR can remove support for old TypeScript versions as a breaking change:
 1. Update the root `package.json` `devDependency`
 1. Update the `SUPPORTED_TYPESCRIPT_VERSIONS` constant in `warnAboutTSVersion.ts`
 1. Update the `versions` constant in `version-check.ts`
-1. Update [Versioning > TypeScript](../Versioning.mdx#typescript)
+1. Update [Users > Dependency Versions > TypeScript](../users/Dependency_Versions.mdx#typescript)
 1. Search for source code comments (excluding `CHANGELOG.md` files) that mention a now-unsupported version of TypeScript.
    - For example, to remove support for v4.3, searches might include:
      - `4.3`

docs/maintenance/Issues.mdx

@@ -78,7 +78,7 @@ In such cases you can forgo the back-and-forth and just skip to the closing step
 
 #### 🐞 "Simple" Bugs
 
-A simple bug is a bug that can be reproduced in a single TS file plus an ESLint config (and possibly a TSConfig) - i.e. an issue reproducible on https://typescript-eslint.io/play.
+A simple bug is a bug that can be reproduced in a single TS file plus an ESLint config (and possibly a TSConfig) - i.e. an issue reproducible on [our playground](/play).
 The vast majority of bug reports fall into this category.
 
 If you cannot reproduce the issue as described using the issue's provided playground reproduction, it has not provided enough information.
@@ -127,7 +127,7 @@ For enhancements meant to limit which kinds of nodes the rule targets, mark the
 #### 🚀 New Rules
 
 We're generally accepting of new rules that meet the above feature request criteria.
-The biggest exception is rules that can roughly be implemented with [`@typescript-eslint/ban-types`](https://typescript-eslint.io/rules/ban-types) and/or [`no-restricted-syntax`](https://eslint.org/docs/latest/rules/no-restricted-syntax).
+The biggest exception is rules that can roughly be implemented with [`@typescript-eslint/ban-types`](/rules/ban-types) and/or [`no-restricted-syntax`](https://eslint.org/docs/latest/rules/no-restricted-syntax).
 
 ## Pruning Old Issues