Update macOS Install Instructions

Updating macOS install instructions together with David.

Closes #5025.

PiperOrigin-RevId: 193374002

1 files changed, 55 insertions, 65 deletions

diff --git a/site/docs/install-os-x.md b/site/docs/install-os-x.md
index b1750a7615..f47ae9c3a4 100644
--- a/site/docs/install-os-x.md
+++ b/site/docs/install-os-x.md
@@ -7,60 +7,23 @@ title: Installing Bazel on macOS
 
 Install Bazel on macOS using one of the following methods:
 
-*   [Use Homebrew (recommended)](#install-on-mac-os-x-homebrew)
-*   [Use the binary installer](#install-with-installer-mac-os-x)
+*   [Use the binary installer (recommended)](#install-with-installer-mac-os-x)
+*   [Use Homebrew](#install-on-mac-os-x-homebrew)
 *   [Compile Bazel from source](install-compile-source.md)
 
 Bazel comes with two completion scripts. After installing Bazel, you can:
 
-*   access the [bash completion script](install.md)
-*   install the [zsh completion script](install.md)
-
-## <a name="install-on-mac-os-x-homebrew"></a>Installing using Homebrew
-
-### 1. Install JDK 8
-
-JDK 8 can be downloaded from [Oracle's JDK
-Page](http://www.oracle.com/technetwork/java/javase/downloads/jdk8-downloads-2133151.html).
-
-Look for "macOS" under "Java SE Development Kit". This will download a DMG
-image with an install wizard.
-
-### 2. Install Homebrew on macOS
-
-Installing Homebrew is a one-time setup:
-
-```bash
-/usr/bin/ruby -e "$(curl -fsSL \
-https://raw.githubusercontent.com/Homebrew/install/master/install)"
-```
-
-### 3. Install Bazel Homebrew Package
-
-```bash
-brew install bazel
-```
-
-You are all set. You can confirm Bazel is installed successfully by running
-
-```bash
-bazel version
-```
-
-Once installed, you can upgrade to a newer version of Bazel with:
-
-```bash
-brew upgrade bazel
-```
+*   Access the [bash completion script](install.md)
+*   Install the [zsh completion script](install.md)
 
 ## <a name="install-with-installer-mac-os-x"></a>Installing using binary installer
 
 The binary installers are on Bazel's [GitHub releases page](https://github.com/bazelbuild/bazel/releases).
 
-The installer contains the Bazel binary and the required JDK. Some additional
-libraries must also be installed for Bazel to work.
+The installer contains the Bazel binary.<sup>1</sup> Some additional libraries must also be
+installed for Bazel to work.
 
-### 1. Install Xcode command line tools
+### Step 1: Install Xcode command line tools
 
 Xcode can be downloaded from the [Apple Developer
 Site](https://developer.apple.com/xcode/downloads/) (this link redirects to
@@ -69,31 +32,19 @@ their App Store).
 For `objc_*` and `ios_*` rule support, you must have Xcode 6.1 or later with iOS
 SDK 8.1 installed on your system.
 
-Once Xcode is installed, you can agree to the license agreement for all users with
-the following command:
+Once Xcode is installed, accept the license agreement for all users with the following command:
 
 ```
 sudo xcodebuild -license accept
 ```
 
-### 2. Download the Bazel installer
-
-**Note:** In the installer file names listed in this document, replace
-`<version>` with the appropriate Bazel version number.
-
-Go to Bazel's [GitHub releases page](https://github.com/bazelbuild/bazel/releases).
+### Step 2: Download the Bazel installer
 
-Download the binary installer `bazel-<version>-installer-darwin-x86_64.sh`. This
-installer contains the Bazel binary and the required JDK, and can be used even
-if a JDK is already installed.
+Next, download the Bazel binary installer named `bazel-<version>-installer-darwin-x86_64.sh` from the [Bazel releases page on GitHub](https://github.com/bazelbuild/bazel/releases).
 
-Note that `bazel-<version>-without-jdk-installer-darwin-x86_64.sh` is a version
-of the installer without embedded JDK 8. Only use this installer if you already
-have JDK 8 installed.
+### Step 3: Run the installer
 
-### 3. Run the installer
-
-Run the installer:
+Run the Bazel installer as follows:
 
 <pre>
 chmod +x bazel-<version>-installer-darwin-x86_64.sh
@@ -104,7 +55,7 @@ The `--user` flag installs Bazel to the `$HOME/bin` directory on your system and
 sets the `.bazelrc` path to `$HOME/.bazelrc`. Use the `--help` command to see
 additional installation options.
 
-### 4. Set up your environment
+### Step 4: Set up your environment
 
 If you ran the Bazel installer with the `--user` flag as above, the Bazel
 executable is installed in your `$HOME/bin` directory. It's a good idea to add
@@ -116,10 +67,49 @@ export PATH="$PATH:$HOME/bin"
 
 You can also add this command to your `~/.bashrc` or `~/.profile` file.
 
-You are all set. You can confirm Bazel is installed successfully by running
+All set! You can confirm Bazel is installed successfully by running the following command:
+
 ```bash
 bazel version
 ```
+To update to a newer release of Bazel, download and install the desired version.
+
+_<sup>1</sup>Note that Bazel includes an embedded JDK, which can be used even if a JDK is already
+installed. `bazel-<version>-without-jdk-installer-linux-x86_64.sh` is a version of the installer
+without an embedded JDK. Only use this installer if you already have JDK 8 installed. Later JDK
+versions are not supported._
+
+## <a name="install-on-mac-os-x-homebrew"></a>Installing using Homebrew
+
+### Step 1: Install the JDK
+
+Download the JDK from [Oracle's JDK Page](http://www.oracle.com/technetwork/java/javase/downloads/jdk8-downloads-2133151.html). Look for "macOS" under "Java SE Development Kit" and download JDK version 8.
+
+### Step 2: Install Homebrew on macOS
+
+Install Homebrew (a one-time step):
+
+```bash
+/usr/bin/ruby -e "$(curl -fsSL \
+https://raw.githubusercontent.com/Homebrew/install/master/install)"
+```
+
+### Step 3: Install the Bazel Homebrew package
 
-When Bazel is installed using the binary installer, updating Bazel is only
-possible by downloading and installing a new release.
+Install the Bazel package via Homebrew as follows:
+
+```bash
+brew install bazel
+```
+
+All set! You can confirm Bazel is installed successfully by running the following command:
+
+```bash
+bazel version
+```
+
+Once installed, you can upgrade to a newer version of Bazel using the following command:
+
+```bash
+brew upgrade bazel
+```