diff --git a/docs/local-dev/cli-build-system.md b/docs/local-dev/cli-build-system.md
index eef0a68af0..4b8d2410dc 100644
--- a/docs/local-dev/cli-build-system.md
+++ b/docs/local-dev/cli-build-system.md
@@ -143,9 +143,38 @@ configurations in turn build on top of the lint rules from
 
 In a standard Backstage setup, each individual package has its own lint
 configuration, along with a root configuration that applies to the entire
-project. Each configuration is initially one that simply extends a base
-configuration provided by the Backstage CLI, but they can be customized to fit
-the needs of each package.
+project. The configuration in each package starts out as a standard configuration
+that is determined based on the package role, but it can be customized to fit the needs of each package.
+
+A minimal `.eslintrc.js` configuration now looks like this:
+
+```js
+module.exports = require('@backstage/cli/config/eslint-factory')(__dirname);
+```
+
+But you can provide custom overrides for each package using the optional second argument:
+
+```js
+module.exports = require('@backstage/cli/config/eslint-factory')(__dirname, {
+  ignorePatterns: ['templates/'],
+  rules: {
+    'jest/expect-expect': 'off',
+  },
+});
+```
+
+The configuration factory also provides utilities for extending the configuration in ways that are otherwise very cumbersome to do with plain ESLint, particularly for rules like `no-restricted-syntax`. These are the extra keys that are available:
+
+| Key                     | Description                                                        |
+| ----------------------- | ------------------------------------------------------------------ |
+| `tsRules`               | Additional rules to apply to TypeScript files                      |
+| `testRules`             | Additional rules to apply to tests files                           |
+| `restrictedImports`     | Additional paths to add to `no-restricted-imports`                 |
+| `restrictedSrcImports`  | Additional paths to add to `no-restricted-imports` in src files    |
+| `restrictedTestImports` | Additional paths to add to `no-restricted-imports` in test files   |
+| `restrictedSyntax`      | Additional patterns to add to `no-restricted-syntax`               |
+| `restrictedSrcSyntax`   | Additional patterns to add to `no-restricted-syntax` in src files  |
+| `restrictedTestSyntax`  | Additional patterns to add to `no-restricted-syntax` in test files |
 
 ## Type Checking
 
diff --git a/docs/tutorials/package-role-migration.md b/docs/tutorials/package-role-migration.md
index bdc50fc54d..d9d9c8c91a 100644
--- a/docs/tutorials/package-role-migration.md
+++ b/docs/tutorials/package-role-migration.md
@@ -90,26 +90,7 @@ If you in the end do not want to use this exact script setup, it is still recomm
 
 ### Step 3 - Migrate package ESLint configurations
 
-An area that has been simplified as part of the move to package roles is the ESLint configuration. Rather than having each package select which configuration they want (and getting it wrong), they now use a shared configuration factory that utilizes the package role.
-
-A minimal `.eslintrc.js` configuration now looks like this:
-
-```js
-module.exports = require('@backstage/cli/config/eslint-factory')(__dirname);
-```
-
-You can provide custom overrides for each package using the optional second argument:
-
-```js
-module.exports = require('@backstage/cli/config/eslint-factory')(__dirname, {
-  ignorePatterns: ['templates/'],
-  rules: {
-    'jest/expect-expect': 'off',
-  },
-});
-```
-
-The configuration factory also provides utilities for extending the configuration in ways that are otherwise very cumbersome to do with plain ESLint, particularly for rules like `no-restricted-syntax`. You can read more about that in the [build system documentation](./not-found#TODO).
+An area that has been simplified as part of the move to package roles is the ESLint configuration. Rather than having each package select which configuration they want (and getting it wrong), they now use a shared configuration factory that utilizes the package role. You can read more about the new configuration setup in the [build system documentation](../local-dev/cli-build-system#linting).
 
 To migrate the ESLint configuration of all packages in your project, run the following command: