More precise descriptions of project reference-related editor options.

packages/documentation/copy/en/project-config/Compiler Options.md

@@ -465,7 +465,7 @@ tsc app.ts util.ts --target esnext --outfile index.js
 </td>
 </tr>
 <tr class="option-description odd"><td colspan="3">
-<p>Reduce the number of projects loaded automatically by TypeScript.</p>
+<p>Avoid searching for symbols across referenced projects in code editors.</p>
 </td></tr>
 
 <tr class='even' name='disableSizeLimit'>
@@ -498,7 +498,7 @@ tsc app.ts util.ts --target esnext --outfile index.js
 </td>
 </tr>
 <tr class="option-description even"><td colspan="3">
-<p>Disable preferring source files instead of declaration files when referencing composite projects.</p>
+<p>When editing code, only consult declaration files from referenced projects.</p>
 </td></tr>
 
 <tr class='odd' name='downlevelIteration'>

packages/tsconfig-reference/copy/en/options/disableReferencedProjectLoad.md

@@ -1,8 +1,10 @@
 ---
 display: "Disable Referenced Project Load"
-oneline: "Reduce the number of projects loaded automatically by TypeScript."
+oneline: "Avoid searching for symbols across referenced projects in code editors."
 ---
 
-In multi-project TypeScript programs, TypeScript will load all of the available projects into memory in order to provide accurate results for editor responses which require a full knowledge graph like 'Find All References'.
+In multi-project TypeScript programs, TypeScript will load all referenced projects into memory in order to provide accurate results for editor responses which require a full knowledge graph like *Find all References* and *Rename*.
+
+If your project is large, you can use the flag `disableReferencedProjectLoad` to avoid loading referenced projects to answer these questions.
+Instead, referenced projects will only be searched if files of the referenced projects are already open in the editor.
 
-If your project is large, you can use the flag `disableReferencedProjectLoad` to disable the automatic loading of all projects. Instead, projects are loaded dynamically as you open files through your editor.

packages/tsconfig-reference/copy/en/options/disableSolutionSearching.md

@@ -3,6 +3,8 @@ display: "Disable Solution Searching"
 oneline: "Opt a project out of multi-project reference checking when editing."
 ---
 
-When working with [composite TypeScript projects](/docs/handbook/project-references.html), this option provides a way to declare that you do not want a project to be included when using features like _find all references_ or _jump to definition_ in an editor.
+When working with [composite TypeScript projects](/docs/handbook/project-references.html), this option provides a way to tell editors not to probe in parent directories for an owning "workspace-style" or "solution-style" `tsconfig.json`.
+
+TypeScript's language service will typically search for workspace-style configuarations when using features like _Find all References_.
 
 This flag is something you can use to increase responsiveness in large composite projects.

packages/tsconfig-reference/copy/en/options/disableSourceOfProjectReferenceRedirect.md

@@ -1,7 +1,49 @@
 ---
-display: "Disable Source Project Reference Redirect"
-oneline: "Disable preferring source files instead of declaration files when referencing composite projects."
+display: "Disable Redirections to Project Reference Source Files"
+oneline: "When editing code, only consult declaration files from referenced projects."
 ---
 
-When working with [composite TypeScript projects](/docs/handbook/project-references.html), this option provides a way to go [back to the pre-3.7](/docs/handbook/release-notes/typescript-3-7.html#build-free-editing-with-project-references) behavior where d.ts files were used to as the boundaries between modules.
-In 3.7 the source of truth is now your TypeScript files.
+When editing a project with [project references](/docs/handbook/project-references.html), the TypeScript language service does not require us to build all dependencies so that generated declaration files are available.
+This is subtle, because this behavior means things usually "just work" in the editor, but differs from how project reference builds work, and warrants explanation.
+
+When building project references, the compiler always expects declaration files to be generated so that less code can be held in memory at once.
+This behavior works for performing a full build, but is often confusing when editing code.
+When referencing code from another project, most people expect the changes to be available immediately in the editor.
+
+For example, imagine making the following change to `projectB/src/setColor.ts`
+
+```diff ts
+  export Options {
+      hue: number;
+      saturation: number;
+-     value: number;
++     lightness: number;
+  }
+
+  export function setColor(options: Options): void {
+      // ...
+  }
+```
+
+If we want to update `projectA/src/draw.ts` to call `setColor` with `lightness` instead of `value` as so:
+
+```diff ts
+  function draw() {
+      // ...
+      setColor({
+          hue: getUserSetting("hue"),
+          saturation: getUserSetting("saturation"),
+-         value: getUserSetting("value"),
++         lightness: getUserSetting("lightness"),
+      })
+  }
+```
+
+we don't want to stop what we're doing and build `projectB` before we can get accurate errors in `projectA`, so TypeScript prefers reading source `.ts` files instead of generated `.d.ts` files if they're around.
+
+This behavior makes editing easier, but comes at a cost.
+Each file has to be resolved back to its source, and that source will likely take longer to parse and type-check than the expected declaration files.
+In larger codebases, this extra work can feel very slow.
+
+The `disableSourceOfProjectReferenceRedirect` option allows developers to opt out of loading source files over declaration files in the editor ([just as it worked before TypeScript 3.7](/docs/handbook/release-notes/typescript-3-7.html#build-free-editing-with-project-references)).
+As a result, dependencies will need to be build with declaration files in order to get accurate error-checking, code completion, and other editor features in a project with references.

packages/tsconfig-reference/scripts/schema/result/schema.json

@@ -230,9 +230,9 @@
               "markdownDescription": "Output compiler performance information after building.\n\nSee more: https://www.typescriptlang.org/tsconfig#diagnostics"
             },
             "disableReferencedProjectLoad": {
-              "description": "Reduce the number of projects loaded automatically by TypeScript.",
+              "description": "Avoid searching for symbols across referenced projects in code editors.",
               "type": "boolean",
-              "markdownDescription": "Reduce the number of projects loaded automatically by TypeScript.\n\nSee more: https://www.typescriptlang.org/tsconfig#disableReferencedProjectLoad"
+              "markdownDescription": "Avoid searching for symbols across referenced projects in code editors.\n\nSee more: https://www.typescriptlang.org/tsconfig#disableReferencedProjectLoad"
             },
             "noPropertyAccessFromIndexSignature": {
               "description": "Enforces using indexed accessors for keys declared using an indexed type.",
@@ -1011,9 +1011,9 @@
               "markdownDescription": "Output more detailed compiler performance information after building.\n\nSee more: https://www.typescriptlang.org/tsconfig#extendedDiagnostics"
             },
             "disableSourceOfProjectReferenceRedirect": {
-              "description": "Disable preferring source files instead of declaration files when referencing composite projects.",
+              "description": "When editing code, only consult declaration files from referenced projects.",
               "type": "boolean",
-              "markdownDescription": "Disable preferring source files instead of declaration files when referencing composite projects.\n\nSee more: https://www.typescriptlang.org/tsconfig#disableSourceOfProjectReferenceRedirect"
+              "markdownDescription": "When editing code, only consult declaration files from referenced projects.\n\nSee more: https://www.typescriptlang.org/tsconfig#disableSourceOfProjectReferenceRedirect"
             },
             "disableSolutionSearching": {
               "description": "Opt a project out of multi-project reference checking when editing.",