Polish documentation.

--
MOS_MIGRATED_REVID=88821025

6 files changed, 63 insertions, 58 deletions

diff --git a/docs/FAQ.md b/docs/FAQ.md
index fca9aa6024..3b62ff8a13 100644
--- a/docs/FAQ.md
+++ b/docs/FAQ.md
@@ -13,8 +13,9 @@ What is special about Bazel?
 Bazel was designed to fit the way software is developed at Google. It
 has the following features:
 
-* Multi-language support: Bazel supports Java and C++ out of the box,
-  and can be extended to support arbitrary programming languages.
+* Multi-language support: Bazel supports Java, Objective-C and C++ out
+  of the box, and can be extended to support arbitrary programming
+  languages.
 
 * High-level build language: Projects are described in the BUILD
   language, a concise text format that describes a project as sets of
@@ -106,7 +107,7 @@ that this is fast enough for most of our users.
 How does the Google development process work?
 ----------------------------------------------
 
-For our server code, we use the following development workflow:
+For our server code base, we use the following development workflow:
 
 * All of our server code base is in a single, gigantic version control
   system.
@@ -119,7 +120,7 @@ For our server code, we use the following development workflow:
 * Branching is primarily used for managing releases, so everybody
   develops their software at head.
 
-Bazel is a cornerstones of this philosophy: since Bazel requires all
+Bazel is a cornerstone of this philosophy: since Bazel requires all
 dependencies to be fully specified, we can predict which programs and
 tests are affected by a change, and vet them before submission.
 
@@ -185,11 +186,11 @@ straightforward, provided a JDK is available for the platform.
 What about Windows?
 -------------------
 
-We have experimented with a Windows port using MinGW/MSYS (see
-README.windows), but have no plans to invest in this port right
-now. Due to its Unix heritage, porting Bazel is significant work. For
-example, Bazel uses symlinks extensively, which has varying levels of
-support across Windows versions.
+We have experimented with a Windows port
+[using MinGW/MSYS](windows.md), but have no plans to invest in this
+port right now. Due to its Unix heritage, porting Bazel is significant
+work. For example, Bazel uses symlinks extensively, which has varying
+levels of support across Windows versions.
 
 
 What should I not use Bazel for?
@@ -220,19 +221,8 @@ versions multiple times every month.
 
 In short, except for features marked as experimental, at any point in
 time, Bazel should Just Work. Changes to non-experimental rules will
-be backward compatible.
-
-You can recognize the different experimental features as follows:
-
-* Options: Experimental features start with --experimental_.
-
-* Rules: Experimental rules are undocumented in the
-  build encyclopedia. TODO(bazel-team): add link.
-
-* Attributes: Experimental rule attributes are undocumented in the
-  build encyclopedia. TODO(bazel-team): add link.
-
-* TODO(bazel-team): document skylark status more precisely.
+be backward compatible. A more detailed list of feature support
+statuses can be found in our [support document](support.md).
 
 
 How stable is Bazel as a binary?
@@ -247,7 +237,7 @@ How can I start using Bazel?
 
 See our [getting started doc](getting-started.md)
 
-TODO(bazel-team): more doc links
+TODO(bazel-team): link to an index of all our docs.
 
 
 Why do I need to have a tools/ directory in my source tree?
@@ -265,11 +255,11 @@ do this in a directory called "tools".
 Bazel allows tools such as the JDK to live outside your workspace, but
 the configuration data for this (where is the JDK, where is the C++
 compiler?) still needs to be somewhere, and that place is also the
-tools/ directory.
+`tools/` directory.
 
-Bazel comes with a base_workspace/ directory, containing a minimal set
+Bazel comes with a `base_workspace/` directory, containing a minimal set
 of configuration files, suitable for running toolchains from standard
-system directories, e.g., /usr/bin/.
+system directories, e.g., `/usr/bin/`.
 
 
 Doesn't Docker solve the reproducibility problems?
@@ -284,9 +274,10 @@ It does not address reproducibility with regard to changes in the
 source code.  Running Make with an imperfectly written Makefile inside a
 Docker container can still yield unpredictable results.
 
-Inside Google, we check in tools for reproducibility.  In this way, we
-can vet changes to tools ("upgrade GCC to 4.6.1") with the same
-mechanism as changes to base libraries ("fix bounds check in OpenSSL").
+Inside Google, we check tools into source control for reproducibility.
+In this way, we can vet changes to tools ("upgrade GCC to 4.6.1") with
+the same mechanism as changes to base libraries ("fix bounds check in
+OpenSSL").
 
 
 Will Bazel make my builds reproducible automatically?
@@ -311,7 +302,7 @@ will need to take some extra care:
     traversal is randomized in many programming languages.
 
 TODO(bazel-team): maybe this should be part of the skylark docs
-instead.
+instead, or the genrule docs?
 
 
 Do you have binary releases?
@@ -357,9 +348,11 @@ files for python:
   https://github.com/google/bazel/blob/master/base_workspace/tools/build_rules/py_rules.bzl
   https://github.com/google/bazel/tree/master/base_workspace/examples/py
 
-Our internal Python rules support internal use-cases which rely heavily
-on native extensions, and its supporting infrastructure is specific to
-us, so we have no plans to open-source it.
+We are working on opening up a subset of our internal Python rules, so
+they can be used as helper scripts as part of a build.
+
+We currently have no plans to provide packaging up of self-contained
+Python binaries.
 
 
 
@@ -407,7 +400,8 @@ We are reachable at bazel-discuss@googlegroups.com.
 Where do I report bugs?
 -----------------------
 
-Send us e-mail at bazel-discuss@googlegroups.com.
+Send e-mail to bazel-discuss@googlegroups.com, or file a bug at
+[on github](https://github.com/google/bazel/issues).
 
 
 
diff --git a/docs/getting-started.md b/docs/getting-started.md
index ba5523ed08..f67810f0c5 100644
--- a/docs/getting-started.md
+++ b/docs/getting-started.md
@@ -69,7 +69,7 @@ Writing Your Own Build Rules
 
 Now you can start adding your own build rules. This example assumes that
 _my-project/_ is a Java project.  See the
-[build encyclopedia](https://github.com/google/bazel/blob/master/docs/historical/build-encyclopedia.html)
+[build encyclopedia](build-encyclopedia.html)
 for advice on writing rules for other languages.
 
 Note that when we ran "bazel build" above, the third argument started with a
@@ -101,7 +101,7 @@ Python, but each build rule looks like a Python function call and you can use
 "hello-world"). `srcs` lists the Java source files Bazel should
 compile into a Java binary.  `glob(["**/*.java"])` is a handy
 shorthand for "recursively include every file that ends with .java" (see the
-[user manual](https://github.com/google/bazel/blob/master/docs/historical/bazel-user-manual.html)
+[user manual](bazel-user-manual.html)
 for more information about globbing). Replace `com.example.ProjectRunner` with
 the class that contains the main method.
 
@@ -271,7 +271,7 @@ INFO: Running command line: bazel-bin/my-project/java/com/example/cmdline/runner
 Hi!
 ```
 
-See the [build encyclopedia](https://github.com/google/bazel/blob/master/docs/historical/build-encyclopedia.html) for more visibility options.
+See the [build encyclopedia](build-encyclopedia.html) for more visibility options.
 
 Deploying
 ---------
@@ -307,9 +307,9 @@ Next Steps
 ----------
 
 You can now create your own targets and compose them.  See the [build
-encyclopedia](https://github.com/google/bazel/blob/master/docs/historical/build-encyclopedia.html)
+encyclopedia](build-encyclopedia.html)
 and Bazel
-[user manual](https://github.com/google/bazel/blob/master/docs/historical/bazel-user-manual.html)
+[user manual](bazel-user-manual.html)
 for more information.
 [Let us know](https://groups.google.com/forum/#!forum/bazel-discuss)
 if you have any questions!
diff --git a/docs/install.md b/docs/install.md
index e7bd9f4882..557fcd5e69 100644
--- a/docs/install.md
+++ b/docs/install.md
@@ -39,9 +39,10 @@ To build Bazel on Ubuntu:
 
 Using Bazel on Mac OS X requires:
 
-* Xcode and Xcode command line tools
-* MacPorts or Homebrew for installing required packages
-* A JDK 8 installed
+* The Xcode command line tools. Xcode can be downloaded from
+  [Apbple's developer site](https://developer.apple.com/xcode/downloads/).
+* MacPorts or Homebrew for installing required packages.
+* An installation of JDK 8.
 
 To build Bazel on Mac OS X:
 
@@ -59,17 +60,25 @@ To build Bazel on Mac OS X:
         $ cd bazel
         $ ./compile.sh
 
-## Running Bazel
+3. Run it
+
+        $ ./output/bazel help
 
-The Bazel executable is located at `<bazel_home>/output/bazel`.
 
-You must run Bazel from within a _workspace directory_. Bazel provides a default
-workspace directory with sample `BUILD` files and source code in
-`<bazel_home>/base_workspace`. The default workspace contains files and
-directories that must be present in order for Bazel to work. If you want to
-build from source outside the default workspace directory, copy the entire
-`base_workspace` directory to the new location before adding your `BUILD` and
-source files.
+## Running Bazel
+
+The Bazel executable is located at `output/bazel`, under the source
+tree root.
+
+You must run Bazel from within source code tree, which is properly
+configured for use with Bazel. We call such a tree a _workspace
+directory_. Bazel provides a default workspace directory with sample
+`BUILD` files and source code in `base_workspace`. The default
+workspace contains files and directories that must be present in order
+for Bazel to work. If you want to build from source outside the
+default workspace directory, copy the entire `base_workspace`
+directory to the new location before adding your `BUILD` and source
+files.
 
 Build a sample Java application:
 
diff --git a/docs/bazel-query-v2.html b/docs/query.html
index 4481580a77..4481580a77 100644
--- a/docs/bazel-query-v2.html
+++ b/docs/query.html
diff --git a/docs/roadmap.md b/docs/roadmap.md
index 1ecc6d36ea..dae285f084 100644
--- a/docs/roadmap.md
+++ b/docs/roadmap.md
@@ -46,9 +46,8 @@ Alpha users will need to build Bazel from source; we will not provide binary
 releases until the beta. We will accept code contributions, but may need to
 reject or defer code contributions related to beta features still under
 development. Some features will be fully supported
-henceforward, others are still experimental or partially supported; see
-bazel/docs/governance.md for details.
-
+henceforward, others are still experimental or partially supported;
+see our [feature support document](support.md) for details.
 
 The following features/capabilities will be available in the alpha:
 
diff --git a/docs/support.md b/docs/support.md
index e449d64ce4..576251a7a7 100644
--- a/docs/support.md
+++ b/docs/support.md
@@ -1,15 +1,18 @@
 # Support Policy
 
-We generally avoid making incompatible changes. At Google, we run all of the tests in the entire
-depot before every release and check that there are no regressions. It is much more difficult to do
-that outside of Google, because there is no single source repository that contains everything.
+We generally avoid making backward-incompatible changes. At Google, we
+run all of the tests in the entire depot before every release and
+check that there are no regressions. It is much more difficult to do
+that outside of Google, because there is no single source repository
+that contains everything.
 
 All undocumented features (attributes, rules, "Make" variables, and flags) are subject to change at
 any time without prior notice. Features that are documented but marked *experimental* are also
 subject to change at any time without prior notice. The Skylark macro and rules language (anything
 you write in a `.bzl` file) is still subject to change.
 
-Bugs can be reported in the [GitHub bugtracker](https://github.com/google/bazel/issues). We will
+Bugs can be reported in the
+[GitHub bugtracker](https://github.com/google/bazel/issues). We will
 make an effort to triage all reported issues within 2 business days; we will measure our triaging
 process and regularly report numbers.