docs: update Windows installation and setup docs

Also update the Java Tutorial page to say you have
to install the JDK and set JAVA_HOME.

See https://github.com/bazelbuild/bazel/issues/5208

Change-Id: I14b792589c39f03572518aaff6f6f8e5ca8a65c8

Closes #5617.

Change-Id: I45c841189b0c220365ab9aeeb67f26b32059be4a
PiperOrigin-RevId: 206156529

4 files changed, 48 insertions, 29 deletions

diff --git a/site/docs/android-ndk.md b/site/docs/android-ndk.md
index c59647afb0..cf47487d65 100644
--- a/site/docs/android-ndk.md
+++ b/site/docs/android-ndk.md
@@ -313,7 +313,7 @@ flags.
 
 For example:
 
-```shell
+```
 bazel build //my/cc/jni:target \
       --crosstool_top=@androidndk//:default_crosstool \
       --cpu=<abi> \
@@ -355,7 +355,7 @@ common:android_<abi> --host_crosstool_top=@bazel_tools//tools/cpp:toolchain
 
 Then, to build a `cc_library` for `x86` for example, run:
 
-```shell
+```
 bazel build //my/cc/jni:target --config=android_x86
 ```
 
diff --git a/site/docs/install-compile-source.md b/site/docs/install-compile-source.md
index 7bea209861..9cf1c6e1d9 100644
--- a/site/docs/install-compile-source.md
+++ b/site/docs/install-compile-source.md
@@ -50,19 +50,24 @@ Ensure you have installed:
 *   **JDK 8.** You must install version 8 of the JDK. Versions other than 8 are
     *not* supported.
 
-*   **Python**. Versions 2 and 3 are supported. You *must* install the
+*   **Python**. Versions 2 and 3 are supported. You need the
     Windows-native version (downloadable from [https://www.python.org](https://www.python.org)).
     Versions installed via pacman in MSYS2 will not work.
 
-### 2.  Download and unpack Bazel's distribution archive
+### 2.  Download and unpack Bazel's source files (distribution archive)
 
-Download `bazel-<version>-dist.zip` from the [release page](https://github.com/bazelbuild/bazel/releases).
+Download `bazel-<version>-dist.zip` from [GitHub](https://github.com/bazelbuild/bazel/releases),
+e.g. `bazel-0.15.2-dist.zip`.
 
 **Note:** There is a **single, architecture-independent** distribution archive. There are no architecture-specific or OS-specific distribution archives.
 
-We recommend to also verify the signature made by our [release key](https://bazel.build/bazel-release.pub.gpg) 48457EE0.
+**Note:** You have to use the distribution archive to build Bazel from source.
+You cannot use a source tree cloned from GitHub. (The distribution archive
+contains generated source files that are required for bootstrapping and are not
+part of the normal Git source tree.)
 
-The distribution archive contains generated files in addition to the versioned sources, so this step _cannot_ be short cut by checking out the source tree.
+We recommend to also verify the signature made by our
+[release key](https://bazel.build/bazel-release.pub.gpg) 48457EE0.
 
 ### 3.  Bootstrap Bazel
 
@@ -88,7 +93,8 @@ Bazel binary, without an embedded JDK. You can copy it to a directory in the
     *   Either `BAZEL_VS` or `BAZEL_VC` (they are *not* the same): Set to the
         path to the Visual Studio directory (BAZEL\_V<b>S</b>) or to the Visual
         C++ directory (BAZEL\_V<b>C</b>). Setting one of them is enough.
-    *   `BAZEL_SH`: Set to the path of the MSYS2 `bash.exe`.
+    *   `BAZEL_SH`: Path of the MSYS2 `bash.exe`. See the command in the
+        examples below.
 
         Do not set this to `C:\Windows\System32\bash.exe`. (You have that file
         if you installed Windows Subsystem for Linux.) Bazel does not support
@@ -99,15 +105,14 @@ Bazel binary, without an embedded JDK. You can copy it to a directory in the
     For example (using BAZEL\_V<b>S</b>):
 
         export BAZEL_VS="C:/Program Files (x86)/Microsoft Visual Studio/2017/BuildTools"
-        export BAZEL_SH="C:/msys64/usr/bin/bash.exe"
+        export BAZEL_SH="$(cygpath -m $(realpath $(which bash)))"
         export PATH="/c/python27:$PATH"
         export JAVA_HOME="C:/Program Files/Java/jdk1.8.0_112"
 
-
     or (using BAZEL\_V<b>C</b>):
 
         export BAZEL_VC="C:/Program Files (x86)/Microsoft Visual Studio/2017/BuildTools/VC"
-        export BAZEL_SH="c:/msys64/usr/bin/bash.exe"
+        export BAZEL_SH="$(cygpath -m $(realpath $(which bash)))"
         export PATH="/c/python27:$PATH"
         export JAVA_HOME="C:/Program Files/Java/jdk1.8.0_112"
 
diff --git a/site/docs/install-windows.md b/site/docs/install-windows.md
index 3cfe8fc8b2..184fd58724 100644
--- a/site/docs/install-windows.md
+++ b/site/docs/install-windows.md
@@ -7,7 +7,7 @@ title: Installing Bazel on Windows
 
 ### Prerequisites
 
-*   64 bit Windows 7 or newer, or <a href="https://msdn.microsoft.com/en-us/library/windows/desktop/ms724832(v=vs.85).aspx">equivalent Windows Server versions</a>
+*   64 bit Windows 7 or newer, or 64 bit Windows Server 2008 R2 or newer
 
 *   [MSYS2 shell](https://msys2.github.io/)
 
@@ -17,31 +17,28 @@ title: Installing Bazel on Windows
 
 ### Getting Bazel
 
-Download Bazel for Windows from our
-[GitHub releases page](https://github.com/bazelbuild/bazel/releases).
-Look for `bazel-<version>-windows-x86_64.exe`, e.g. `bazel-0.13.0-windows-x86_64.exe`.
+[Download Bazel for Windows from GitHub](https://github.com/bazelbuild/bazel/releases).
+Look for `bazel-<version>-windows-x86_64.exe`, e.g. `bazel-0.15.2-windows-x86_64.exe`.
 
-**Tip:** For convenience, rename the downloaded binary to `bazel.exe` and move it to a directory
-that's on your `%PATH%` or add its directory to your `%PATH%`. This way you can run Bazel by
-typing `bazel` in any directory, without typing out the full path.
+**Tip:** Rename the binary to `bazel.exe` and move it to a directory on your
+`%PATH%`, so you can run Bazel by typing `bazel` in any directory.
 
 ### Other ways to get Bazel
 
-You can also get Bazel by:
-
-*   [Installing Bazel using Chocolatey](#install-using-chocolatey)
-*   [Compiling Bazel from source](install-compile-source.html)
+*   [Install Bazel using the Chocolatey package manager](#install-using-chocolatey)
+*   [Compile Bazel from source](install-compile-source.html)
 
 #### Install using Chocolatey
 
-You can install the Bazel package using the [Chocolatey](https://chocolatey.org)
-package manager:
+1.  Install the [Chocolatey](https://chocolatey.org) package manager
+
+2.  Install the Bazel package:
 
-    choco install bazel
+        choco install bazel
 
-This command will install the latest available version of Bazel and
-its dependencies, such as the MSYS2 shell. This will not install Visual C++
-though.
+    This command will install the latest available version of Bazel and
+    its dependencies, such as the MSYS2 shell. This will not install Visual C++
+    though.
 
 See [Chocolatey installation and package maintenance
 guide](https://bazel.build/windows-chocolatey-maintenance.html) for more
diff --git a/site/docs/tutorial/java.md b/site/docs/tutorial/java.md
index 8352229a6b..b1ed79da86 100644
--- a/site/docs/tutorial/java.md
+++ b/site/docs/tutorial/java.md
@@ -27,6 +27,7 @@ In this tutorial you'll learn how to:
 
 *  [Before you begin](#before-you-begin)
    *  [Install Bazel](#install-bazel)
+   *  [Install the JDK](#install-the-jdk)
    *  [Get the sample project](#get-the-sample-project)
 *  [Build with Bazel](#build-with-bazel)
    *  [Set up the workspace](#set-up-the-workspace)
@@ -47,6 +48,23 @@ In this tutorial you'll learn how to:
 To prepare for the tutorial, first [Install Bazel](../install.md) if
 you don't have it installed already.
 
+### Install the JDK
+
+1.  Install Java 8 JDK.
+
+2.  Set the JAVA\_HOME environment variable to point to the JDK.
+    *   On Linux/macOS:
+
+            export JAVA_HOME="$(dirname $(dirname $(realpath $(which javac))))"
+    *   On Windows:
+        1.  Open Control Panel.
+        2.  Go to "System&nbsp;and&nbsp;Security" &gt; "System" &gt; "Advanced&nbsp;System&nbsp;Settings" &gt; "Advanced"&nbsp;tab &gt; "Environment&nbsp;Variables..." .
+        3.  Under the "User&nbsp;variables" list (the one on the top), click "New...".
+        4.  In the "Variable&nbsp;name" field, enter `JAVA_HOME`.
+        5.  Click "Browse&nbsp;Directory...".
+        6.  Navigate to the JDK directory (for example `C:\Program&nbsp;Files\Java\jdk1.8.0_152`).
+        7.  Click "OK" on all dialog windows.
+
 ### Get the sample project
 
 Retrieve the sample project from Bazel's GitHub repository:
@@ -60,7 +78,6 @@ directory and is structured as follows:
 
 ```
 java-tutorial
-│
 ├── BUILD
 ├── src
 │   └── main