docs: recommend messageId over message for reporting rule violations (#…

…18050)

* docs: recommend messageId over message for reporting rule violations

* Update docs/src/extend/custom-rules.md

Co-authored-by: Nicholas C. Zakas <nicholas@humanwhocodes.com>

* Update docs/src/extend/custom-rules.md

Co-authored-by: Josh Goldberg ✨ <git@joshuakgoldberg.com>

---------

Co-authored-by: Nicholas C. Zakas <nicholas@humanwhocodes.com>
Co-authored-by: Josh Goldberg ✨ <git@joshuakgoldberg.com>

docs/src/extend/custom-rules.md

@@ -145,7 +145,8 @@ Additionally, the `context` object has the following methods:
 
 The main method you'll use when writing custom rules is `context.report()`, which publishes a warning or error (depending on the configuration being used). This method accepts a single argument, which is an object containing the following properties:
 
-* `message`: (`string`) The problem message.
+* `messageId`: (`string`) The ID of the message (see [messageIds](#messageids)) (recommended over `message`).
+* `message`: (`string`) The problem message (alternative to `messageId`).
 * `node`: (optional `object`) The AST node related to the problem. If present and `loc` is not specified, then the starting location of the node is used as the location of the problem.
 * `loc`: (optional `object`) Specifies the location of the problem. If both `loc` and `node` are specified, then the location is used from `loc` instead of `node`.
     * `start`: An object of the start location.
@@ -192,9 +193,11 @@ The node contains all the information necessary to figure out the line and colum
 
 #### `messageId`s
 
-Instead of typing out messages in both the `context.report()` call and your tests, you can use `messageId`s instead.
+`messageId`s are the recommended approach to reporting messages in `context.report()` calls because of the following benefits:
 
-This allows you to avoid retyping error messages. It also prevents errors reported in different sections of your rule from having out-of-date messages.
+* Rule violation messages can be stored in a central `meta.messages` object for convenient management
+* Rule violation messages do not need to be repeated in both the rule file and rule test file
+* As a result, the barrier for changing rule violation messages is lower, encouraging more frequent contributions to improve and optimize them for the greatest clarity and usefulness
 
 Rule file: