docs: expand on how jest version is determined and common workarounds

README.md

@@ -59,23 +59,43 @@ doing:
 This is included in all configs shared by this plugin, so can be omitted if
 extending them.
 
-The behaviour of some rules (specifically `no-deprecated-functions`) change
-depending on the version of `jest` being used.
+### Jest `version` setting
 
-This setting is detected automatically based off the version of the `jest`
-package installed in `node_modules`, but it can also be provided explicitly if
-desired:
+The behaviour of some rules (specifically [`no-deprecated-functions`][]) change
+depending on the version of Jest being used.
+
+By default, this plugin will attempt to determine the version of Jest
+automatically by looking for Jest in the `node_modules` of _the working directly
+that ESLint is being run from_.
+
+If you're working with a project structure that means Jest is not installed at
+the same directory level as where you run ESLint (such as if you're using a
+mono-repo structure but not hoisting dependencies to the root of the repo) you
+will need to provide the Jest version explicitly:
 
 ```json
 {
   "settings": {
     "jest": {
-      "version": 26
+      "version": 27
     }
   }
 }
 ```
 
+To avoid hard-coding a number, you can also fetch it from the installed version
+of Jest if you use a JavaScript config file such as `.eslintrc.js`:
+
+```js
+module.exports = {
+  settings: {
+    jest: {
+      version: require('jest/package.json').version,
+    },
+  },
+};
+```
+
 ## Shareable configurations
 
 ### Recommended
@@ -226,3 +246,4 @@ https://github.com/istanbuljs/eslint-plugin-istanbul
 [suggest]: https://img.shields.io/badge/-suggest-yellow.svg
 [fixable]: https://img.shields.io/badge/-fixable-green.svg
 [style]: https://img.shields.io/badge/-style-blue.svg
+[`no-deprecated-functions`]: docs/rules/no-deprecated-functions.md

docs/rules/no-deprecated-functions.md

@@ -6,6 +6,10 @@ either been renamed for clarity, or replaced with more powerful APIs.
 While typically these deprecated functions are kept in the codebase for a number
 of majors, eventually they are removed completely.
 
+This rule requires knowing which version of Jest you're using - see
+[this section of the readme](README.md) for details on how that is obtained
+automatically and how you can explicitly provide a version if needed.
+
 ## Rule details
 
 This rule warns about calls to deprecated functions, and provides details on