Clarify documentation about Concepts

--
PiperOrigin-RevId: 147491785
MOS_MIGRATED_REVID=147491785

1 files changed, 29 insertions, 15 deletions

diff --git a/site/versions/master/docs/skylark/concepts.md b/site/versions/master/docs/skylark/concepts.md
index ca5d69db05..2d5430f0f8 100644
--- a/site/versions/master/docs/skylark/concepts.md
+++ b/site/versions/master/docs/skylark/concepts.md
@@ -4,6 +4,7 @@ title: Extensions - Overview
 ---
 # Overview
 
+
 ## Loading an extension
 
 Extensions are files with the `.bzl` extension. Use the `load` statement to
@@ -35,23 +36,28 @@ example is perfectly legal (please note when to use quotation marks).
 load(":my_rules.bzl", "some_rule", nice_alias = "some_other_rule")
 ```
 
-Symbols starting with `_` are private and cannot be loaded from other files.
-Visibility doesn't affect loading (yet): you don't need to use `exports_files`
-to make a `.bzl` file visible.
+In a `.bzl` file, symbols starting with `_` are private and cannot be loaded
+from another file. Visibility doesn't affect loading (yet): you don't need to
+use `exports_files` to make a `.bzl` file visible.
 
 ## Macros and rules
 
-A [macro](macros.md) is a function that instantiates rules. The
-function is evaluated as soon as the BUILD file is read. Bazel has little
-information about macros: if your macro generates a `genrule`, Bazel will behave
-as if you wrote the `genrule`. As a result, `bazel query` will only list the
-generated `genrule`.
+A [macro](macros.md) is a function that instantiates rules. It is useful when a
+BUILD file is getting too repetitive or too complex, as it allows you to reuse
+some code. The function is evaluated as soon as the BUILD file is read. After
+the evaluation of the BUILD file, Bazel has little information about macros: if
+your macro generates a `genrule`, Bazel will behave as if you wrote the
+`genrule`. As a result, `bazel query` will only list the generated `genrule`.
 
-A [rule](rules.md) is more powerful than a macro, as it can access
-Bazel internals and have full control over what is going on. It may for example
-pass information to other rules.
+A [rule](rules.md) is more powerful than a macro. It can access Bazel internals
+and have full control over what is going on. It may for example pass information
+to other rules.
 
-If a macro becomes complex, it is often a good idea to make it a rule.
+If you want to reuse simple logic, start with a macro. If a macro becomes
+complex, it is often a good idea to make it a rule. Support for a new language
+is typically done with a rule. Rules are for advanced users: we expect that most
+people will never have to write one, they will only load and call existing
+rules.
 
 ## Evaluation model
 
@@ -59,17 +65,20 @@ A build consists of three phases.
 
 * **Loading phase**. First, we load and evaluate all extensions and all BUILD
   files that are needed for the build. The execution of the BUILD files simply
-  instantiates rules. This is where macros are evaluated.
+  instantiates rules (each time a rule is called, it gets added to a graph).
+  This is where macros are evaluated.
 
 * **Analysis phase**. The code of the rules is executed (their `implementation`
   function), and actions are instantiated. An action describes how to generate
   a set of outputs from a set of inputs, e.g. "run gcc on hello.c and get
   hello.o". It is important to note that we have to list explicitly which
-  files will be generated before executing the actual commands.
+  files will be generated before executing the actual commands. In other words,
+  the analysis phase takes the graph generated by the loading phase and
+  generates an action graph.
 
 * **Execution phase**. Actions are executed, when at least one of their outputs is
   required. If a file is missing or if a command fails to generate one output,
-  the build fails. Tests are run during this phase, as they are actions.
+  the build fails. Tests are also run during this phase.
 
 Bazel uses parallelism to read, parse and evaluate the `.bzl` files and `BUILD`
 files. A file is read at most once per build and the result of the evaluation is
@@ -77,6 +86,11 @@ cached and reused. A file is evaluated only once all its dependencies (`load()`
 statements) have been resolved. By design, loading a `.bzl` file has no visible
 side-effect, it only defines values and functions.
 
+Bazel tries to be clever: it uses dependency analysis to know which files must
+be loaded, which rules must be analyzed, and which actions must be executed. For
+example, if a rule generates actions that we don't need for the current build,
+they will not be executed.
+
 ## Syntax
 
 The extension language (Skylark) is a superset of the