docs: resubmit pr 17115 doc changes (#17291)

credits: https://github.com/domdomegg

Refs:
* #17225
* #17115

docs/src/extend/custom-rules.md

@@ -614,12 +614,17 @@ You can also access comments through many of `sourceCode`'s methods using the `i
 
 Rules may export a `schema` property, which is a [JSON Schema](https://json-schema.org/) format description of a rule's options which will be used by ESLint to validate configuration options and prevent invalid or unexpected inputs before they are passed to the rule in `context.options`.
 
-There are two formats for a rule's exported `schema`. The first is a full JSON Schema object describing all possible options the rule accepts, including the rule's error level as the first argument and any optional arguments thereafter.
+There are two formats for a rule's exported `schema`:
 
-However, to simplify schema creation, rules may also export an array of schemas for each optional positional argument. ESLint automatically validates the required error level first. For example, the `yoda` rule accepts a primary mode argument, as well as an extra options object with named properties.
+1. A full JSON Schema object describing all possible options the rule accepts.
+2. An array of JSON Schema objects for each optional positional argument.
+
+In both cases, these should exclude the [severity](../use/configure/rules#rule-severities), as ESLint automatically validates this first.
+
+For example, the `yoda` rule accepts a primary mode argument of `"always"` or `"never"`, as well as an extra options object with an optional property `exceptRange`:
 
 ```js
-// "yoda": [2, "never", { "exceptRange": true }]
+// "yoda": ["error", "never", { "exceptRange": true }]
 module.exports = {
     meta: {
         schema: [
@@ -640,12 +645,10 @@ module.exports = {
 };
 ```
 
-In the preceding example, the error level is assumed to be the first argument. It is followed by the first optional argument, a string that may be either `"always"` or `"never"`. The final optional argument is an object, which may have a boolean property named `exceptRange`.
-
-To learn more about JSON Schema, we recommend looking at some examples in [website](https://json-schema.org/learn/) to start, and also reading [Understanding JSON Schema](https://json-schema.org/understanding-json-schema/) (a free ebook).
-
 **Note:** If your rule schema uses JSON schema [`$ref`](https://json-schema.org/understanding-json-schema/structuring.html#ref) properties, you must use the full JSON Schema object rather than the array of positional property schemas. This is because ESLint transforms the array shorthand into a single schema without updating references that makes them incorrect (they are ignored).
 
+To learn more about JSON Schema, we recommend looking at some examples on the [JSON Schema website](https://json-schema.org/learn/), or reading the free [Understanding JSON Schema](https://json-schema.org/understanding-json-schema/) ebook.
+
 ### Accessing Shebangs
 
 [Shebangs (#!)](https://en.wikipedia.org/wiki/Shebang_(Unix)) are represented by the unique tokens of type `"Shebang"`. They are treated as comments and can be accessed by the methods outlined in the [Accessing Comments](#accessing-comments) section, such as `sourceCode.getAllComments()`.