Update recursive glob docs.

PiperOrigin-RevId: 195288040

1 files changed, 18 insertions, 6 deletions

diff --git a/site/docs/skylark/build-style.md b/site/docs/skylark/build-style.md
index c48484a4d6..30bae9a90e 100644
--- a/site/docs/skylark/build-style.md
+++ b/site/docs/skylark/build-style.md
@@ -143,17 +143,29 @@ dependencies of several targets into a variable reduces maintainability, makes
 it impossible for tools to change the dependencies of a target and can lead to
 unused dependencies.
 
-
 ## Globs
 
-Do not use recursive globs (e.g., `glob(["**/*.java"])`). Recursive globs
-make BUILD files difficult to read, as they skip subdirectories containing
-BUILD files. Non-recursive globs are generally acceptable, see
-language-specific advice below for details.
-
 Indicate "no targets" with `[]`. Do not use a glob that matches nothing: it
 is more error-prone and less obvious than an empty list.
 
+### Recursive
+
+Do not use recursive globs (for example, `glob(["**/*.java"])`).
+
+Recursive globs make BUILD files difficult to reason about because they skip
+subdirectories containing BUILD files.
+
+Recursive globs are generally less efficient than having a BUILD file per
+directory with a dependency graph defined between them as this enables better
+forge caching and parallelism.
+
+We recommend authoring a BUILD file per directory and defining a dependency
+graph between them instead.
+
+### Non-recursive
+
+Non-recursive globs are generally acceptable.
+
 ## Other conventions
 
  * Use uppercase and underscores to declare constants (e.g. `GLOBAL_CONSTANT`),