Clarify documentation about outputs.

RELNOTES: None.
PiperOrigin-RevId: 178664333

site/docs/skylark/rules.md

diff --git a/site/docs/skylark/rules.md b/site/docs/skylark/rules.md
index 87763ad..d9a3e40 100644
--- a/site/docs/skylark/rules.md
+++ b/site/docs/skylark/rules.md
@@ -173,20 +173,30 @@
 ## <a name="output-files"></a> Output files
 
 A target can declare output files, which must be generated by the target's
-actions. There are three ways to create output files:
+actions. Each output file must have exactly one generating action.
+
+There are multiple ways to have declared outputs:
 
 * If the rule is marked `executable`, it creates an output file of the same name
   as the rule's. [See example](https://github.com/bazelbuild/examples/blob/master/rules/executable/executable.bzl)
 
-* The rule can declare default `outputs`, which are always generated.
+* The rule can declare outputs using the `outputs` argument of the
+  [rule](lib/globals.html#rule) function.
   [See example](https://github.com/bazelbuild/examples/blob/master/rules/default_outputs/extension.bzl)
 
-* The rule can have output or output list type attributes. In that case the
-  output files come from the actual attribute values.
+* The rule can have [output](lib/attr.html#output) or [output_list](lib/attr.html#output_list)
+  attributes. In that case the output files come from the actual attribute values.
   [See example](https://github.com/bazelbuild/examples/blob/master/rules/custom_outputs/extension.bzl)
 
-Each output file must have exactly one generating action. See the
-[library](lib/ctx.html#outputs) for more context.
+We call them "declared outputs" because they are associated with a label. You
+can refer to declared outputs using a label on the command-line or in a `BUILD`
+file. In the implementation function, use [ctx.outputs](lib/ctx.html#outputs)
+for accessing declared outputs.
+
+The rule can also create extra output files during the analysis phase using the
+[ctx.actions.declare_file](lib/actions.html#declare_file) function. This is
+more flexible, but those files are not declared: they don't have any associated
+label.
 
 ## Default outputs
 
@@ -200,8 +210,8 @@
   This is the case, for example, if you use a rule in the `srcs` attribute of a
   `genrule`.
 
-Use the `files` provider to specify the default outputs of a rule.
-If left unspecified, it will contain all the declared outputs.
+In the `DefaultInfo` provider, the `files` field specifies the default outputs
+of a rule. If left unspecified, it will contain all the declared outputs.
 
 ```python
 def _impl(ctx):
@@ -210,9 +220,12 @@
 ```
 
 This can be useful for exposing files generated with
-[ctx.actions.declare_file](lib/actions.html#declare_file). You can also
-have "implicit outputs", i.e., files that are declared in the rule, but
-not in the default outputs (like `_deploy.jar` in `java_binary`).
+[ctx.actions.declare_file](lib/actions.html#declare_file).
+
+An "implicit output" is a declared output that is not in the default outputs. In
+other words, it is not generated by default. Users can refer to its label to
+build the file explicitly. Use the `files` mentioned above if you need implicit
+outputs (like `_deploy.jar` files generated by `java_binary`).
 
 ## Actions