Simplify Skylark landing page, other minor fixes.

--
MOS_MIGRATED_REVID=102655878

3 files changed, 15 insertions, 35 deletions

diff --git a/site/docs/skylark/concepts.md b/site/docs/skylark/concepts.md
index c068cbcc58..068d577321 100644
--- a/site/docs/skylark/concepts.md
+++ b/site/docs/skylark/concepts.md
@@ -1,11 +1,9 @@
 # Concepts
 
-Skylark is the code name of the extension mechanism. It lets you write custom
-build rules as well as compose existing ones into [macros](macros.md).
+## Loading a Skylark extension
 
-## Loading a Skylark module
-
-Use the `load` statement to import a symbol from a Skylark module.
+Use the `load` statement to import a symbol from a <code>.bzl</code> Skylark
+extension.
 
 ```python
 load("/build_tools/rules/maprule", "maprule")
@@ -30,13 +28,12 @@ list can contain both aliases and regular symbol names. The following example is
 perfectly legal (please note when to use quotation marks).
 
 ```python
-load("/path/to/my_rules", "some_rule", nice_alias = "some_other_rule", additional_alias = "one_more_rule")
+load("/path/to/my_rules", "some_rule", nice_alias = "some_other_rule")
 ```
 
-Visibility doesn't affect loading. You don't need to use `exports_files`
-to make a Skylark file visible.
-
 Symbols starting with `_` are private and cannot be loaded from other files.
+Visibility doesn't affect loading: you don't need to use `exports_files` to make
+a Skylark file visible.
 
 ## Macros and rules
 
@@ -57,7 +54,7 @@ If a macro becomes complex, it is often a good idea to make it a rule.
 
 A build consists of three phases.
 
-* **Loading phase**. First, we load and evaluate all Skylark modules and all BUILD
+* **Loading phase**. First, we load and evaluate all Skylark 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.
 
diff --git a/site/docs/skylark/index.md b/site/docs/skylark/index.md
index 9c07e1b6be..71a282accb 100644
--- a/site/docs/skylark/index.md
+++ b/site/docs/skylark/index.md
@@ -1,28 +1,9 @@
 # Custom rules
 
-Bazel includes an API for writing your own rules, called Skylark. Skylark is a
-work-in-progress project, which allows extending Bazel with new rules or macros
-(composition of rules and macros).
+Skylark is the code name of the extension mechanism for Bazel. It lets you write
+[custom build rules](rules.md) as well as compose existing ones into
+[macros](macros.md).
 
-## Goals
-
-* **Power to the user**. We want to allow users to write new rules in a simple
-  language without having to understand all of Bazel's internals. The core
-  contributors have to write or review all changes to native Bazel rules (both
-  inside and outside of Google). This is a lot of work and we have to push back
-  on new rules.
-* **Simplicity**. Skylark has been designed to be as simple as possible. Contrary
-  to native rules, the code is very short and does not rely on complex
-  inheritance.
-
-* **Faster development**. With Skylark, rules are stored in the source tree. Modify one
-  rule file and run Bazel to see the result immediately. Before Skylark, we
-  had to rebuild and restart Bazel before seeing a change, this slowed down the
-  development process a lot.
-
-* **Faster release cycle**. Update one rule file, commit the changes to
-  version control and everyone will use it when they sync. No need to wait for
-  a native rule to be released with the next Bazel binary.
 
 ## Getting started
 
diff --git a/site/docs/skylark/macros.md b/site/docs/skylark/macros.md
index 1970227e58..5ed162b4d4 100644
--- a/site/docs/skylark/macros.md
+++ b/site/docs/skylark/macros.md
@@ -1,8 +1,6 @@
 Macros
 ======
 
-**Status: Stable**
-
 Macro creation
 --------------
 
@@ -13,7 +11,11 @@ anymore: Bazel sees only the set of rules they created.
 Native rules can be instantiated from the `native` module, e.g.
 
 ```python
-native.cc_library(name = x)
+def my_macro(name):
+  native.cc_library(
+    name = name,
+    srcs = ["main.cc"],
+  )
 ```
 
 If you need to know the package name (i.e. which BUILD file is calling the