Split the mobile app tutorial into separate Android and iOS tutorials and eliminate the backend server tutorial.

RELNOTES: None.
PiperOrigin-RevId: 164653190

8 files changed, 318 insertions, 540 deletions

diff --git a/site/_layouts/documentation.html b/site/_layouts/documentation.html
index 7ec4ef5b09..95600acb29 100644
--- a/site/_layouts/documentation.html
+++ b/site/_layouts/documentation.html
@@ -53,21 +53,8 @@ nav: docs
                   <li><a href="/versions/{{ site.version }}/tutorial/java.html">Build a Java Project</a></li>
                   <li><a href="/versions/{{ site.version }}/tutorial/cpp.html">Build a C++ Project</a></li>
                   <li><a href="/versions/{{ site.version }}/tutorial/cpp-use-cases.html">Common C++ Use Cases</a></li>
-                  <li>
-                    <a class="sidebar-nav-heading" href="#app-menu"
-                       data-toggle="collapse" aria-expanded="false" aria-controls="app-menu">
-                      Build a Mobile Application
-                    </a>
-                    <ul class="collapse sidebar-nav sidebar-submenu" id="app-menu">
-                      <li><a href="/versions/{{ site.version }}/tutorial/app.html">Introduction</a></li>
-                      <li><a href="/versions/{{ site.version }}/tutorial/environment.html">Set Up Your Environment</a></li>
-                      <li><a href="/versions/{{ site.version }}/tutorial/workspace.html">Set Up a Workspace</a></li>
-                      <li><a href="/versions/{{ site.version }}/tutorial/android-app.html">Build an Android App</a></li>
-                      <li><a href="/versions/{{ site.version }}/tutorial/ios-app.html">Build an iOS App</a></li>
-                      <li><a href="/versions/{{ site.version }}/tutorial/backend-server.html">Build the Backend Server</a></li>
-                      <li><a href="/versions/{{ site.version }}/tutorial/review.html">Review</a></li>
-                    </ul>
-                  </li>
+                  <li><a href="/versions/{{ site.version }}/tutorial/android-app.html">Build an Android App</a></li>
+                  <li><a href="/versions/{{ site.version }}/tutorial/ios-app.html">Build an iOS App</a></li>
                 </ul>
               </li>
             </ul>
diff --git a/site/docs/tutorial/android-app.md b/site/docs/tutorial/android-app.md
index 1c6c7222d0..9211e0e0b2 100644
--- a/site/docs/tutorial/android-app.md
+++ b/site/docs/tutorial/android-app.md
@@ -1,58 +1,117 @@
 ---
 layout: documentation
-title: Tutorial - Build an Android App
+title: Build Tutorial - Android
 ---
 
-# Tutorial - Build an Android App
+Introduction to Bazel: Build an Android App
+==========
 
-The sample Android app in this tutorial is a very simple application that makes
-an HTTP connection to the [backend server](backend-server.md) and displays the
-resulting response.
+In this tutorial, you will learn how to build a simple Android app. You'll do
+the following:
 
-Here, you'll do the following:
+*   [Set up your environment](#set-up-your-environment)
+    *   [Install Bazel](#install-bazel)
+    *   [Install Android Studio](#install-android-studio)
+    *   [Get the sample project](#get-the-sample-project)
+*   [Set up a workspace](#set-up-a-workspace)
+    *   [Create a WORKSPACE file](#create-a-workspace-file)
+    *   [Update the WORKSPACE file](#update-the-workspace-file)
+*   [Review the source files](#review-the-source-files)
+*   [Create a BUILD file](#create-a-build-file)
+    *   [Add an android_library rule](#add-an-android_library-rule)
+    *   [Add an android_binary rule](#add_an-android_binary-rule)
+*   [Build the app](#build-the-app)
+*   [Find the build outputs](#find-the-build-outputs)
+*   [Run the app](#run-the-app)
+*   [Review  your work](#review-your-work)
 
-*   Review the source files for the app
-*   Update the `WORKSPACE` file
-*   Create a `BUILD` file
-*   Run the build
-*   Find the build outputs
-*   Run the app
+## Set up your environment
 
-## Review the source files
+To get started, install Bazel and Android Studio, and get the sample project.
 
-Let's take a look at the source files for the app. These are located in
-`$WORKSPACE/android/`.
+### Install Bazel
 
-The key files and directories are:
+Follow the [installation instructions](../install.md) to install Bazel and
+its dependencies.
 
-<table class="table table-condensed table-striped">
-<thead>
-<tr>
-<td>Name</td>
-<td>Location</td>
-</tr>
-</thead>
-<tbody>
-<tr>
-<td>Manifest file</td>
-<td><code>src/main/java/com/google/bazel/example/android/AndroidManifest.xml</code></td>
-</tr>
-<tr>
-<td>Activity source file</td>
-<td><code>src/main/java/com/google/bazel/example/android/activities/MainActivity.java</code></td>
-</tr>
-<tr>
-<td>Resource file directory</td>
-<td><code>src/main/java/com/google/bazel/example/android/res/</code></td>
-</tr>
-</tbody>
-</table>
+### Install Android Studio
 
-Note that you're just looking at these files now to become familiar with the
-structure of the app. You don't have to edit any of the source files to complete
-this tutorial.
+Download and install Android Studio as described in [Install Android Studio](https://developer.android.com/sdk/index.html).
+
+The installer does not automatically set the `ANDROID_HOME` variable.
+Set it to the location of the Android SDK, which defaults to `$HOME/Android/Sdk/`
+.
+
+For example:
+
+`export ANDROID_HOME=$HOME/Android/Sdk/`
+
+For convenience, add the above statement to your `~/.bashrc` file.
+
+### Get the sample project
+
+You also need to get the sample project for the tutorial from GitHub. The repo
+has two branches: `source-only` and `master`. The `source-only` branch contains
+the source files for the project only. You'll use the files in this branch in
+this tutorial. The `master` branch contains both the source files and completed
+Bazel `WORKSPACE` and `BUILD` files. You can use the files in this branch to
+check your work when you've completed the tutorial steps.
 
-## Update the WORKSPACE file
+Enter the following at the command line to get the files in the `source-only`
+branch:
+
+```bash
+cd $HOME
+git clone -b source-only https://github.com/bazelbuild/examples
+```
+
+The `git clone` command creates a directory named `$HOME/examples/`. This
+directory contains several sample projects for Bazel. The project files for this
+tutorial are in `$HOME/examples/tutorial/android`.
+
+## Set up a workspace
+
+A [workspace](../build-ref.html#workspaces) is a directory that contains the
+source files for one or more software projects, as well as a `WORKSPACE` file
+and `BUILD` files that contain the instructions that Bazel uses to build
+the software. The workspace may also contain symbolic links to output
+directories.
+
+A workspace directory can be located anywhere on your filesystem and is denoted
+by the presence of the `WORKSPACE` file at its root. In this tutorial, your
+workspace directory is `$HOME/examples/tutorial/`, which contains the sample
+project files you cloned from the GitHub repo in the previous step.
+
+Note that Bazel itself doesn't make any requirements about how you organize
+source files in your workspace. The sample source files in this tutorial are
+organized according to conventions for the target platform.
+
+For your convenience, set the `$WORKSPACE` environment variable now to refer to
+your workspace directory. At the command line, enter:
+
+```bash
+export WORKSPACE=$HOME/examples/tutorial
+```
+
+### Create a WORKSPACE file
+
+Every workspace must have a text file named `WORKSPACE` located in the top-level
+workspace directory. This file may be empty or it may contain references
+to [external dependencies](../external.html) required to build the
+software.
+
+For now, you'll create an empty `WORKSPACE` file, which simply serves to
+identify the workspace directory. In later steps, you'll update the file to add
+external dependency information.
+
+Enter the following at the command line:
+
+```bash
+touch $WORKSPACE/WORKSPACE
+```
+This creates the empty `WORKSPACE` file.
+
+### Update the WORKSPACE file
 
 Bazel needs to run the Android SDK
 [build tools](https://developer.android.com/tools/revisions/build-tools.html)
@@ -72,9 +131,9 @@ android_sdk_repository(
 )
 ```
 
-This will use the Android SDK specified referenced by the `ANDROID_HOME`
-environment variable, and automatically detect the latest build tools
-version installed within that location.
+This will use the Android SDK referenced by the `ANDROID_HOME` environment
+variable, and automatically detect the latest build tools version installed
+within that location.
 
 Alternatively, you can explicitly specify the location of the Android
 SDK and build tools version to use by including the `path` and
@@ -99,19 +158,53 @@ file:
 android_ndk_repository(
     name = "androidndk",
     # Replace with the Android NDK API level
-    api_level = 21
+    api_level = 23
 )
 ```
 
 `api_level` is the version of the Android API the SDK and the NDK target
-(for example, 19 for Android K and 21 for Android L). It's not necessary to set
-the API levels to the same value for the SDK and NDK.
+(for example, 23 for Android 6.0 and 25 for Android 7.1). It's not necessary to
+set the API levels to the same value for the SDK and NDK.
 [This web page](https://developer.android.com/ndk/guides/stable_apis.html)
 contains a map from Android releases to NDK-supported API levels.
 
-Similar to `android_sdk_repository`, the path to the Android NDK is inferred from
-the `ANDROID_NDK_HOME` environment variable by default. The path can also be
-explicitly specified with a `path` attribute on `android_ndk_repository`.
+Similar to `android_sdk_repository`, the path to the Android NDK is inferred
+from the `ANDROID_NDK_HOME` environment variable by default. The path can also
+be explicitly specified with a `path` attribute on `android_ndk_repository`.
+
+## Review the source files
+
+Let's take a look at the source files for the app. These are located in
+`$WORKSPACE/android/`.
+
+The key files and directories are:
+
+<table class="table table-condensed table-striped">
+<thead>
+<tr>
+<td>Name</td>
+<td>Location</td>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td>Manifest file</td>
+<td><code>src/main/java/com/google/bazel/example/android/AndroidManifest.xml</code></td>
+</tr>
+<tr>
+<td>Activity source file</td>
+<td><code>src/main/java/com/google/bazel/example/android/activities/MainActivity.java</code></td>
+</tr>
+<tr>
+<td>Resource file directory</td>
+<td><code>src/main/java/com/google/bazel/example/android/res/</code></td>
+</tr>
+</tbody>
+</table>
+
+Note that you're just looking at these files now to become familiar with the
+structure of the app. You don't have to edit any of the source files to complete
+this tutorial.
 
 ## Create a BUILD file
 
@@ -121,7 +214,7 @@ software libraries or executables -- and their dependencies. These dependencies
 may be source files in your workspace or other build outputs. `BUILD` files are
 written in the Bazel *build language*.
 
-`BUILD` files are part of concept in Bazel known as the *package hierarchy*.
+`BUILD` files are part of a concept in Bazel known as the *package hierarchy*.
 The package hierarchy is a logical structure that overlays the directory
 structure in your workspace. Each [package](../build-ref.html#packages) is a
 directory (and its subdirectories) that contains a related set of source files
@@ -201,7 +294,7 @@ Now, save and close the file. You can compare your `BUILD` file to the
 [completed example](https://github.com/bazelbuild/examples/blob/master/tutorial/android/BUILD)
 in the `master` branch of the GitHub repo.
 
-## Run the build
+## Build the app
 
 You use the
 [`bazel`](../bazel-user-manual.html) command-line tool to run builds, execute
@@ -228,7 +321,7 @@ build the target that follows. The target is specified as the name of a build
 rule inside a `BUILD` file, with along with the package path relative to
 your workspace directory. Note that you can sometimes omit the package path
 or target name, depending on your current working directory at the command
-line and the name of the target. See [Labels](../build-ref.html#labels) in
+line and the name of the target. See [Labels](../build-ref.html#labels) in the
 *Bazel Concepts and Terminology* page for more information about target labels
 and paths.
 
@@ -269,6 +362,10 @@ ls $WORKSPACE/bazel-bin/android
 
 ## Run the app
 
+**NOTE:** The app launches standalone but requires a backend server in order to
+produce output. See the README file in the sample project directory to find out
+how to build the backend server.
+
 You can now deploy the app to a connected Android device or emulator from the
 command line using the
 [`bazel mobile-install`](../bazel-user-manual.html#mobile-install)
@@ -291,7 +388,26 @@ Note that the `mobile-install` subcommand also supports the
 flag that can be used to deploy only those parts of the app that have changed
 since the last deployment.
 
-## What's next
-
-Now that you've built a sample app for Android, it's time to do the same for
-the [iOS app](ios-app.md).
+## Review your work
+
+In this tutorial, you used Bazel to build an Android app. To accomplish that,
+you:
+
+*   Set up your environment by installing Bazel and Android Studio, and
+    downloading the sample project
+*   Set up a Bazel [workspace](workspace.md) that contained the source code
+    for the app and a `WORKSPACE` file that identifies the top level of the
+    workspace directory
+*   Updated the `WORKSPACE` file to contain references to the required
+    external dependencies
+*   Created a `BUILD` file
+*   Ran Bazel to build the app
+*   Deployed and ran the app on an Android emulator and device
+
+The built app is located in the `$WORKSPACE/bazel-bin` directory.
+
+Note that completed `WORKSPACE` and `BUILD` files for this tutorial are located
+in the
+[master branch](https://github.com/bazelbuild/examples/tree/master/tutorial)
+of the GitHub repo. You can compare your work to the completed files for
+additional help or troubleshooting.
diff --git a/site/docs/tutorial/app.md b/site/docs/tutorial/app.md
deleted file mode 100644
index b3b274c2d5..0000000000
--- a/site/docs/tutorial/app.md
+++ /dev/null
@@ -1,45 +0,0 @@
----
-layout: documentation
-title: Build Mobile Application
----
-
-# Build Mobile Application
-
-You can use Bazel to build a variety of software outputs, including
-Linux and macOS (OS X) applications written in Java, C++ and Objective-C. You can
-also use Bazel to build software for other platforms or written in other
-languages.
-
-This tutorial shows how to use Bazel to build the following:
-
-*   An Android app
-*   An iOS app
-*   A mobile backend server running on App Engine
-
-In this tutorial, you'll learn how to:
-
-*   Set up a Bazel workspace and create a `WORKSPACE` file
-*   Create `BUILD` files that contain the instructions used by Bazel to build
-    the software
-*   Run builds using the Bazel command line tool
-
-## Requirements
-
-You can follow the steps in this tutorial on either a Linux or Mac OS X system.
-However, you can only build the iOS app if you are running Bazel on OS X. If
-you are using Linux, you can skip the iOS instructions and still complete
-the rest of the tutorial steps.
-
-## Sample project
-
-You don't have to write your own mobile apps and backend server to use this
-tutorial. Instead, you'll use a sample project hosted on GitHub. The sample
-project is hosted at the following location:
-
-[https://github.com/bazelbuild/examples/](https://github.com/bazelbuild/examples/)
-
-You'll grab the sample project files in the next step in this tutorial.
-
-## What's next
-
-Let's start off by [setting up](environment.md) the tutorial environment.
diff --git a/site/docs/tutorial/backend-server.md b/site/docs/tutorial/backend-server.md
deleted file mode 100644
index cfcbc2a50c..0000000000
--- a/site/docs/tutorial/backend-server.md
+++ /dev/null
@@ -1,238 +0,0 @@
----
-layout: documentation
-title: Tutorial - Build the Backend Server
----
-
-# Tutorial - Build the Backend Server
-
-The backend server is a simple web application that runs on Google App Engine
-and responds to incoming HTTP requests from the sample Android and iOS apps.
-
-Here, you'll do the following:
-
-*   Review the source files for the app
-*   Update the `WORKSPACE` file
-*   Create a `BUILD` file
-*   Run the build
-*   Find the build outputs
-*   Run the application on a local development server
-*   Deploy to Google App Engine
-
-Bazel provides a set of [App Engine build rules](https://github.com/bazelbuild/rules_appengine)
-written using the [Skylark](../skylark/index.html) framework. You'll use
-these in the steps below to build the application.
-
-## Review the source files
-
-The source files for the backend server are located in `$WORKSPACE/backend/`.
-
-The key files and directories are:
-
-<table class="table table-condensed table-striped">
-<thead>
-<tr>
-<td>Name</td>
-<td>Location</td>
-</tr>
-</thead>
-<tbody>
-<tr>
-<td>Source file directory</td>
-<td><code>src/main/java/com/google/bazel/example/app/</code></td>
-</tr>
-<tr>
-<td>Web application metadata directory</td>
-<td><code>webapp/WEB-INF/</code></td>
-</tr>
-</tbody>
-</table>
-
-## Update the WORKSPACE file
-
-As with the Android app, you must add references to
-[external dependencies](../external.html) to your `WORKSPACE`
-file. For the backend server, these are references to the App Engine SDK,
-the Java Servlet SDK and other libraries needed to build the App Engine
-applications.
-
-### Add the App Engine rule
-
-When you built the Android app, you added a reference to the location on your
-filesystem where you downloaded and installed the Android SDK. For the
-backend server, however, you'll give Bazel instructions for downloading the
-required App Engine SDK package from a remote server. This is optional. You
-can also download and install the SDK manually on your filesystem and reference
-it from that location as described in the
-[App Engine rule documentation](https://github.com/bazelbuild/rules_appengine).
-
-Add the following to your `WORKSPACE` file:
-
-```python
-http_archive(
-    name = "io_bazel_rules_appengine",
-    sha256 = "f4fb98f31248fca5822a9aec37dc362105e57bc28e17c5611a8b99f1d94b37a4",
-    strip_prefix = "rules_appengine-0.0.6",
-    url = "https://github.com/bazelbuild/rules_appengine/archive/0.0.6.tar.gz",
-)
-load("@io_bazel_rules_appengine//appengine:appengine.bzl", "appengine_repositories")
-appengine_repositories()
-```
-
-[`http_archive`](../be/workspace.html#http_archive) downloads the
-AppEngine rules from a GitHub archive. We could also have used
-[`git_repository`](../be/workspace.html#git_repository) to fetch the rules
-directly from the Git repository.
-
-The next two lines use the `appengine_repositories` function defined in
-these rules to download the libraries and SDK needed to build AppEngine
-applications.
-
-Now, save and close the file. You can compare your `WORKSPACE` file to the
-[completed example](https://github.com/bazelbuild/examples//blob/master/tutorial/WORKSPACE)
-in the `master` branch of the GitHub repo.
-
-## Create a BUILD file
-
-Now that you have set up the external dependencies, you can go ahead and create
-the `BUILD` file for the backend server, as you did previously for the sample
-Android and iOS apps.
-
-Open your new `BUILD` file for editing:
-
-```bash
-vi $WORKSPACE/backend/BUILD
-```
-
-### Add a java_binary rule
-
-Add the following to your `BUILD` file:
-
-```python
-java_binary(
-    name = "app",
-    srcs = glob(["src/main/java/**/*.java"]),
-    main_class = "does.not.exist",
-    deps = [
-        "@io_bazel_rules_appengine//appengine:javax.servlet.api",
-    ],
-)
-```
-
-The [`java_binary`](../be/java.html#java_binary) tells Bazel
-how to build a Java `.jar` library for your application, plus a wrapper shell
-script that launches the application code from the specified main class. Here,
-we're using this rule instead of the
-[`java_library`](../be/java.html#java_library) because we need
-the `.jar` file to contain all the dependencies required to build the final
-App Engine `.war` file. For this reason, we specify a bogus class name
-for the `main_class` attribute.
-
-### Add an appengine_war rule
-
-Add the following to your `BUILD` file:
-
-```python
-load("@io_bazel_rules_appengine//appengine:appengine.bzl", "appengine_war")
-
-appengine_war(
-    name = "backend",
-    data = [":webapp"],
-    data_path = "/backend/webapp",
-    jars = [":app_deploy.jar"],
-)
-
-filegroup(
-    name = "webapp",
-    srcs = glob(["webapp/**/*"]),
-)
-```
-
-The [`appengine_war`](../be/appengine.html#appengine_war)
-rule builds the final App Engine `war` file from the library `.jar` file and web
-application metadata files in the `webapp` directory.
-
-Save and close the file. Again, the
-[completed example](https://github.com/google/bazel-examples/blob/master/tutorial/backend/BUILD)
-is in the `master` branch of the GitHub repo.
-
-## Run the build
-
-Make sure that your current working directory is inside your Bazel workspace:
-
-```bash
-cd $WORKSPACE
-```
-
-Now, enter the following to build the server:
-
-```bash
-bazel build //backend:backend
-```
-
-Bazel now launches and builds the server files. During the build process, its
-output will appear similar to the following:
-
-```bash
-INFO: Found 1 target...
-Target //backend:backend up-to-date:
-  bazel-bin/backend/backend.war
-  bazel-bin/backend/backend.deploy
-  bazel-bin/backend/backend
-INFO: Elapsed time: 56.867s, Critical Path: 2.72s
-```
-
-## Find the build outputs
-
-The `.war` file and other outputs are located in the
-`$WORKSPACE/bazel-bin/backend` directory.
-
-In particular, the `appengine_war` rule generates scripts that you can use to
-run your backend locally or deploy it to Google App Engine:
-
-## Run the application on a local development server
-
-Here, you'll start a local App Engine development server in your environment and
-run your application on it.
-
-To run the application, enter the following:
-
-```bash
-bazel-bin/backend/backend --port=12345
-```
-
-Your application will be available at `http://localhost:12345`
-
-## Deploy to Google App Engine
-
-You can also deploy the application to the live App Engine serving
-environment on Google Cloud Platform. For this scenario, you must first create
-a new Cloud Platform project and App Engine application using the Google Cloud
-Platform Console.
-Follow [this link](https://console.cloud.google.com/projectselector/appengine/create?lang=java&st=true)
-to perform these actions.
-
-Build the target that allows to deploy to App Engine:
-
-```bash
-bazel build --java_toolchain=@io_bazel_rules_appengine//appengine:jdk7 //backend:backend.deploy
-```
-
-Then, to deploy the application, enter the following:
-
-```bash
-bazel-bin/backend/backend.deploy <project-id>
-```
-
-The deployment script prompts you to authorize access to Google Cloud Platform.
-After you have authorized access the first time, you can deploy the application
-using the `bazel` command and the following rule target:
-
-```bash
-bazel run //backend:backend.deploy <project-id>
-```
-
-Your application URL will be `http://<project-id>.appspot.com`.
-
-## What's next
-
-Now let's [review](review.md) the tutorial steps.
diff --git a/site/docs/tutorial/environment.md b/site/docs/tutorial/environment.md
deleted file mode 100644
index c9f9043499..0000000000
--- a/site/docs/tutorial/environment.md
+++ /dev/null
@@ -1,70 +0,0 @@
----
-layout: documentation
-title: Tutorial - Set Up Your Environment
----
-
-# Tutorial - Set Up Your Environment
-
-The first step in this tutorial is to set up your environment.
-
-Here, you'll do the following:
-
-*   Install Bazel
-*   Install Android Studio
-*   Install Xcode (macOS only)
-*   Get the sample project from the GitHub repo
-
-## Install Bazel
-
-Follow the [installation instructions](../install.md) to install Bazel and
-its dependencies.
-
-## Install Android Studio
-
-Download and install Android Studio as described in [Install Android Studio](https://developer.android.com/sdk/index.html).
-
-The installer does not automatically set the `ANDROID_HOME` variable.
-Set it to the location of the Android SDK, which defaults to `$HOME/Android/Sdk/`
-.
-
-For example:
-
-`export ANDROID_HOME=$HOME/Android/Sdk/`
-
-For convenience, add the above statement to your `~/.bashrc` file.
-
-## Install Xcode (macOS only)
-
-If you are following the steps in this tutorial on macOS, download and
-install [Xcode](https://developer.apple.com/xcode/downloads/). The Xcode
-download contains the iOS libraries, the Objective-C compiler, and other tools
-required by Bazel to build iOS apps.
-
-## Get the sample project
-
-You also need to get the sample project for the tutorial from GitHub:
-
-[https://github.com/bazelbuild/examples/](https://github.com/bazelbuild/examples/)
-
-The GitHub repo has two branches: `source-only` and `master`. The `source-only`
-branch contains the source files for the project only. You'll use the files in
-this branch in this tutorial. The `master` branch contains both the source files
-and completed Bazel `WORKSPACE` and `BUILD` files. You can use the files in this
-branch to check your work when you've completed the tutorial steps.
-
-Enter the following at the command line to get the files in the `source-only`
-branch:
-
-```bash
-cd $HOME
-git clone -b source-only https://github.com/bazelbuild/examples
-```
-
-The `git clone` command creates a directory named `$HOME/examples/`. This
-directory contains several sample projects for Bazel. The project files for this
-tutorial are in `$HOME/examples/tutorial`.
-
-## What's next
-
-Now that you have set up your environment, you can
-[set up a Bazel workspace](workspace.md).
diff --git a/site/docs/tutorial/ios-app.md b/site/docs/tutorial/ios-app.md
index ff6a5b1964..90a3364298 100644
--- a/site/docs/tutorial/ios-app.md
+++ b/site/docs/tutorial/ios-app.md
@@ -1,28 +1,114 @@
 ---
 layout: documentation
-title: Tutorial - Build an iOS App
+title: Build Tutorial - iOS
 ---
 
-# Tutorial - Build an iOS App
+Introduction to Bazel: Build an iOS App
+==========
 
-Like the [Android app](android-app.md) you built in the previous step, the iOS
-app is a simple mobile app that communicates with the [backend server](backend-server.md).
+In this tutorial, you will learn how to build a simple iOS app. You'll do the
+following:
 
-If you're following the steps in this tutorial on macOS, you can go ahead
-and build the sample iOS app as described below. If you are on Linux, skip ahead
-to the [next step](backend-server.md).
+*   [Set up your environment](#set-up-your-environment)
+    *   [Install Bazel](#install-bazel)
+    *   [Install Xcode](#install-xcode)
+    *   [Get the sample project](#get-the-sample-project)
+*   [Set up a workspace](#set-up-a-workspace)
+    *   [Create a WORKSPACE file](#create-a-workspace-file)
+    *   [Update the WORKSPACE file](#update-the-workspace-file)
+*   [Review the source files](#review-the-source-files)
+*   [Create a BUILD file](#create-a-build-file)
+    *   [Add the rule load statement](#add-the-rule-load-statement)
+    *   [Add an objc_library rule](#add-an-objc_library-rule)
+    *   [Add an ios_application rule](#add_an-ios_application-rule)
+*   [Build and deploy the app](#build-and-deploy-the-app)
+    *   [Build the app for the simulator](#build-the-app-for-the-simulator)
+    *   [Find the build outputs](#find-the-build-outputs)
+    *   [Run and debug the app in the simulator](#run-and-debug-the-app-in-the-simulator)
+    *   [Build the app for a device](#build-the-app-for-a-device)
+    *   [Install the app on a device](#install-the-app-on-a-device)
+*   [Review  your work](#review-your-work)
 
-Here, you'll do the following:
+## Set up your environment
 
-*   Review the source files for the app
-*   Create a `BUILD` file
-*   Build the app for the simulator
-*   Find the build outputs
-*   Run/Debug the app on the simulator
-*   Build the app for a device
-*   Install the app on a device
+To get started, install Bazel and Xcode, and get the sample project.
 
-## Update the WORKSPACE file
+### Install Bazel
+
+Follow the [installation instructions](../install.md) to install Bazel and
+its dependencies.
+
+### Install Xcode
+
+Download and install [Xcode](https://developer.apple.com/xcode/downloads/). The
+Xcode download contains the iOS libraries, the Objective-C compiler, and other
+tools required by Bazel to build iOS apps.
+
+### Get the sample project
+
+You also need to get the sample project for the tutorial from GitHub. The GitHub
+repo has two branches: `source-only` and `master`. The `source-only` branch
+contains the source files for the project only. You'll use the files in this
+branch in this tutorial. The `master` branch contains both the source files
+and completed Bazel `WORKSPACE` and `BUILD` files. You can use the files in this
+branch to check your work when you've completed the tutorial steps.
+
+Enter the following at the command line to get the files in the `source-only`
+branch:
+
+```bash
+cd $HOME
+git clone -b source-only https://github.com/bazelbuild/examples
+```
+
+The `git clone` command creates a directory named `$HOME/examples/`. This
+directory contains several sample projects for Bazel. The project files for this
+tutorial are in `$HOME/examples/tutorial/ios-app`.
+
+## Set up a workspace
+
+A [workspace](../build-ref.html#workspaces) is a directory that contains the
+source files for one or more software projects, as well as a `WORKSPACE` file
+and `BUILD` files that contain the instructions that Bazel uses to build
+the software. The workspace may also contain symbolic links to output
+directories.
+
+A workspace directory can be located anywhere on your filesystem and is denoted
+by the presence of the `WORKSPACE` file at its root. In this tutorial, your
+workspace directory is `$HOME/examples/tutorial/`, which contains the sample
+project files you cloned from the GitHub repo in the previous step.
+
+Note that Bazel itself doesn't make any requirements about how you organize
+source files in your workspace. The sample source files in this tutorial are
+organized according to conventions for the target platform.
+
+For your convenience, set the `$WORKSPACE` environment variable now to refer to
+your workspace directory. At the command line, enter:
+
+```bash
+export WORKSPACE=$HOME/examples/tutorial
+```
+
+### Create a WORKSPACE file
+
+Every workspace must have a text file named `WORKSPACE` located in the top-level
+workspace directory. This file may be empty or it may contain references
+to [external dependencies](../external.html) required to build the
+software.
+
+For now, you'll create an empty `WORKSPACE` file, which simply serves to
+identify the workspace directory. In later steps, you'll update the file to add
+external dependency information.
+
+Enter the following at the command line:
+
+```bash
+touch $WORKSPACE/WORKSPACE
+```
+
+This creates the empty `WORKSPACE` file.
+
+### Update the WORKSPACE file
 
 To build applications for Apple devices, Bazel needs to pull the latest
 [Apple build rules](https://github.com/bazelbuild/rules_apple) from its GitHub
@@ -38,7 +124,7 @@ git_repository(
 
 ## Review the source files
 
-Let's take a look at the source files for the app. These are located in
+Take a look at the source files for the app located in
 `$WORKSPACE/ios-app/UrlGet`. Again, you're just looking at these files now to
 become familiar with the structure of the app. You don't have to edit any of the
 source files to complete this tutorial.
@@ -51,7 +137,7 @@ At a command-line prompt, open your new `BUILD` file for editing:
 vi $WORKSPACE/ios-app/BUILD
 ```
 
-## Add the rule load statement
+### Add the rule load statement
 
 To build iOS targets, Bazel needs to load build rules from its GitHub repository
 whenever the build runs. To make these rules available to your project, add the
@@ -61,7 +147,7 @@ following load statement to the beginning of your `BUILD` file:
 load("@build_bazel_rules_apple//apple:ios.bzl", "ios_application")
 ```
 
-## Add an objc_library rule
+### Add an objc_library rule
 
 Bazel provides several build rules that you can use to build an app for the
 iOS platform. For this tutorial, you'll first use the
@@ -91,7 +177,7 @@ objc_library(
 
 Note the name of the rule, `UrlGetClasses`.
 
-## Add an ios_application rule
+### Add an ios_application rule
 
 The [`ios_application`](../be/objective-c.html#ios_application) rule builds
 the application binary and creates the `.ipa` bundle file.
@@ -119,7 +205,16 @@ Now, save and close the file. You can compare your `BUILD` file to the
 [completed example](https://github.com/bazelbuild/examples/blob/master/tutorial/ios-app/BUILD)
 in the `master` branch of the GitHub repo.
 
-## Build the app for the simulator
+## Build and deploy the app
+
+You are now ready to build your app and deploy it to a simulator and onto an
+iOS device.
+
+**NOTE:** The app launches standalone but requires a backend server in order to
+produce output. See the README file in the sample project directory to find out
+how to build the backend server.
+
+### Build the app for the simulator
 
 Make sure that your current working directory is inside your Bazel workspace:
 
@@ -143,14 +238,12 @@ Target //ios-app:ios-app up-to-date:
 INFO: Elapsed time: 0.565s, Critical Path: 0.44s
 ```
 
-
-
-## Find the build outputs
+### Find the build outputs
 
 The `.ipa` file and other outputs are located in the
 `$WORKSPACE/bazel-bin/ios-app` directory.
 
-## Run/Debug the app on the simulator
+### Run and debug the app in the simulator
 
 You can now run the app from Xcode using the iOS Simulator. First, [generate an Xcode project using Tulsi](http://tulsi.bazel.io/).
 Then, open the project in Xcode, choose an iOS Simulator as the runtime scheme,
@@ -161,7 +254,7 @@ remove a file, or add or change a dependency), you must rebuild the app using
 Bazel, re-generate the Xcode project in Tulsi, and then re-open the project in
 Xcode.
 
-## Build the app for a device
+### Build the app for a device
 
 To build your app so that it installs and launches on an iOS device, Bazel needs
 the appropriate provisioning profile for that device model. Do the following:
@@ -203,12 +296,12 @@ parameter to the `ios_application` build rule in your `BUILD` file.
 You can also use [Tulsi](http://tulsi.bazel.io/docs/gettingstarted.html) to
 build your app using a GUI rather than the command line.
 
-## Install the app on a device
+### Install the app on a device
 
 The easiest way to install the app on the device is to launch Xcode and use the
 `Windows > Devices` command. Select your plugged-in device from the list on the
-left, then add the app by clicking on the "plus" sign under installed apps and
-selecting the `.ipa` that you built.
+left, then add the app by clicking the **Add** (plus sign) button under
+"Installed Apps" and selecting the `.ipa` file that you built.
 
 If your app fails to install on your device, ensure that you are specifying the
 correct provisioning profile in your `BUILD` file (step 4 in the previous
@@ -218,7 +311,24 @@ If your app fails to launch, make sure that your device is part of your
 provisioning profile. The `View Device Logs` button on the `Devices` screen in
 Xcode may provide other information as to what has gone wrong.
 
-## What's next
+## Review your work
+
+In this tutorial, you used Bazel to build an iOS app. To accomplish that, you:
+
+*   Set up your environment by installing Bazel and Xcode, and downloading the
+    sample project
+*   Set up a Bazel [workspace](workspace.md) that contained the source code
+    for the app and a `WORKSPACE` file that identifies the top level of the
+    workspace directory
+*   Updated the `WORKSPACE` file to contain references to the required
+    external dependencies
+*   Created a `BUILD` file
+*   Ran Bazel to build the app for the simulator and an iOS device
+*   Ran the app in the simulator and on an iOS device
+
+The built app is located in the `$WORKSPACE/bazel-bin` directory.
 
-The next step is to build a [backend server](backend-server.md) for the two
-mobile apps you built in this tutorial.
+Completed `WORKSPACE` and `BUILD` files for this tutorial are located in the
+[master branch](https://github.com/bazelbuild/examples/tree/master/tutorial)
+of the GitHub repo. You can compare your work to the completed files for
+additional help or troubleshooting.
diff --git a/site/docs/tutorial/review.md b/site/docs/tutorial/review.md
deleted file mode 100644
index 62d4501ad4..0000000000
--- a/site/docs/tutorial/review.md
+++ /dev/null
@@ -1,29 +0,0 @@
----
-layout: documentation
-title: Tutorial - Review
----
-
-# Tutorial - Review
-
-In this tutorial, you used Bazel to build an [Android app](android-app.md),
-an [iOS app](ios-app.md) and a [backend server](backend-server.md) that runs on
-Google App Engine.
-
-To build these software outputs, you:
-
-*   Set up a Bazel [workspace](workspace.md) that contained the source code
-    for the components and a `WORKSPACE` that identifies the top level of the
-    workspace directory
-*   Created a `BUILD` file for each component
-*   Updated the `WORKSPACE` file to contain references to the required
-    external dependencies
-*   Ran Bazel to build the software components
-
-The built mobile apps and backend server application files are located in the
-`$WORKSPACE/bazel-bin` directory.
-
-Note that completed `WORKSPACE` and `BUILD` files for this tutorial are located
-in the
-[master branch](https://github.com/bazelbuild/examples/tree/master/tutorial)
-of the GitHub repo. You can compare your work to the completed files for
-additional help or troubleshooting.
diff --git a/site/docs/tutorial/workspace.md b/site/docs/tutorial/workspace.md
deleted file mode 100644
index 59115c7e31..0000000000
--- a/site/docs/tutorial/workspace.md
+++ /dev/null
@@ -1,53 +0,0 @@
----
-layout: documentation
-title: Tutorial - Set Up a Workspace
----
-
-# Tutorial - Set Up a Workspace
-
-A [workspace](../build-ref.html#workspaces) is a directory that contains the
-source files for one or more software projects, as well as a `WORKSPACE` file
-and `BUILD` files that contain the instructions that Bazel uses to build
-the software. The workspace may also contain symbolic links to output
-directories.
-
-A workspace directory can be located anywhere on your filesystem. In this
-tutorial, your workspace directory is `$HOME/examples/tutorial/`, which
-contains the sample project files you cloned from the GitHub repo in the
-previous step.
-
-Note that Bazel itself doesn't make any requirements about how you organize
-source files in your workspace. The sample source files in this tutorial are
-organized according to common conventions for Android apps, iOS apps and App
-Engine applications.
-
-For your convenience, set the `$WORKSPACE` environment variable now to refer to
-your workspace directory. At the command line, enter:
-
-```bash
-export WORKSPACE=$HOME/examples/tutorial
-```
-
-## Create a WORKSPACE file
-
-Every workspace must have a text file named `WORKSPACE` located in the top-level
-workspace directory. This file may be empty or it may contain references
-to [external dependencies](../external.html) required to build the
-software.
-
-For now, you'll create an empty `WORKSPACE` file, which simply serves to
-identify the workspace directory. In later steps, you'll update the file to add
-external dependency information.
-
-Enter the following at the command line:
-
-```bash
-touch $WORKSPACE/WORKSPACE
-```
-
-This creates the empty `WORKSPACE` file.
-
-## What's next
-
-Now that you've set up your workspace, you can
-[build the Android app](android-app.md).