diff --git a/site/docs/skylark/index.md b/site/docs/skylark/index.md
index eadbc98..b72b218 100644
--- a/site/docs/skylark/index.md
+++ b/site/docs/skylark/index.md
@@ -4,10 +4,9 @@
 ---
 
 # Custom rules
-Skylark is the name of the extension mechanism in Bazel. It lets you write
-[custom build rules](rules.md) as well as compose existing ones into
-[macros](macros.md).
-
+Skylark is the name of the extension mechanism in Bazel. It lets you add support
+for new languages and tools by writing [custom build rules](rules.md). You can
+also compose existing rules into [macros](macros.md).
 
 ## Getting started
 
diff --git a/site/docs/skylark/rules.md b/site/docs/skylark/rules.md
index 89caaf5..826c252 100644
--- a/site/docs/skylark/rules.md
+++ b/site/docs/skylark/rules.md
@@ -7,11 +7,31 @@
 **Status: Experimental**. We may make breaking changes to the API, but we will
   help you update your code.
 
+A rule defines a series of actions that Bazel should perform on inputs to get a
+set of outputs.  For example, a C++ binary rule might take a set of .cpp
+files (the inputs), run `g++` on them (the action), and return an executable
+file (the output).
+
+Note that, from Bazel's perspective, `g++` and the standard C++ libraries are
+also inputs to this rule. As a rule writer, you must consider not only the
+user-provided inputs to a rule, but also all of the tools and libraries required
+to execute the actions (called _implicit inputs_).
+
 ## Rule creation
 
-In a Skylark extension, use the [rule](lib/globals.html#rule) function
-to create a new rule and store it in a global variable.
-[See example](cookbook.md#empty).
+In a Skylark extension (a .bzl file), use the [rule](lib/globals.html#rule)
+function to create a new rule and store it in a global variable:
+
+```python
+my_rule = rule(...)
+```
+
+See [the cookbook](cookbook.md#empty) for examples. The rule can then be
+loaded by BUILD files:
+
+```python
+load('//some/pkg:whatever.bzl', 'my_rule')
+```
 
 A custom rule can be used just like a native rule. It has a mandatory `name`
 attribute, you can refer to it with a label, and you can see it in
@@ -30,9 +50,9 @@
 
 ```python
 sum = rule(
-    implementation=impl,
-    attrs={
-        "number": attr.int(default=1),
+    implementation = impl,
+    attrs = {
+        "number": attr.int(default = 1),
         "deps": attr.label_list(),
     },
 )
@@ -40,12 +60,16 @@
 
 The following attributes are implicitly added to every rule: `deprecation`,
 `features`, `name`, `tags`, `testonly`, `visibility`. Test rules also have the
-following attributes: `args`, `flaky`, `local`, `shard_count`, `size`, `timeout`.
+following attributes: `args`, `flaky`, `local`, `shard_count`, `size`,
+`timeout`.
 
-To access an attribute, use `ctx.attr.<attribute_name>`. The name and the
-package of a rule are available with `ctx.label.name` and `ctx.label.package`.
+Labels listed in `attr` will be inputs to the rule.
 
-[See example.](cookbook.md#attr)
+To access an attribute in a rule's implementation, use
+`ctx.attr.<attribute_name>`. The name and the package of a rule are available
+with `ctx.label.name` and `ctx.label.package`.
+
+See [an example](cookbook.md#attr) of using `attr` in a rule.
 
 ### <a name="private-attributes"></a> Private Attributes
 
@@ -152,7 +176,7 @@
   output files come from the actual attribute values.
   [See example](cookbook.md#outputs-custom)
 
-All output files must have exactly one generating action. See the
+Each output file must have exactly one generating action. See the
 [library](lib/ctx.html#outputs) for more context.
 
 ## Default outputs
@@ -209,8 +233,9 @@
 compilation fails.
 
 **If an action generates an unknown number of outputs and you want to keep them
-all**, you may group them in a zip file. This way, you will be able to declare
-your output.
+all**, you must group them in a single file (e.g., a zip, tar, or other
+archive format). This way, you will be able to deterministically declare your
+outputs.
 
 **If an action does not list a file it uses as an input**, the action execution
 will most likely result in an error. The file is not guaranteed to be available
diff --git a/src/main/java/com/google/devtools/build/lib/actions/Artifact.java b/src/main/java/com/google/devtools/build/lib/actions/Artifact.java
index b3b8682..fe03f57 100644
--- a/src/main/java/com/google/devtools/build/lib/actions/Artifact.java
+++ b/src/main/java/com/google/devtools/build/lib/actions/Artifact.java
@@ -91,8 +91,14 @@
  */
 @Immutable
 @SkylarkModule(name = "File",
-    doc = "This type represents a file used by the build system. It can be "
-        + "either a source file or a derived file produced by a rule.")
+    doc = "<p>This type represents a file used by the build system. It can be "
+        + "either a source file or a derived file produced by a rule.</p>"
+        + "<p>The File constructor is private, so you cannot call it directly to create new "
+        + "Files. If you have a Skylark rule that needs to create a new File, you might need to "
+        + "add the label to the attrs (if it's an input) or the outputs (if it's an output). Then "
+        + "you can access the File through the rule's <a href='ctx.html'>context</a>. You can "
+        + "also use <a href='ctx.html#new_file'>ctx.new_file</a> to create a new file in the rule "
+        + "implementation.</p>")
 public class Artifact
     implements FileType.HasFilename, ActionInput, SkylarkValue, Comparable<Object> {