docs(tutorial): clean up and elaborate introduction

Author: petebacondarwin

docs/content/tutorial/index.ngdoc

@@ -13,23 +13,25 @@ details for any device.
 <img class="diagram" src="img/tutorial/catalog_screen.png" width="488" height="413" alt="demo
 application running in the browser">
 
-Work through the tutorial to see how Angular makes browsers smarter — without the use of native
-extensions or plug-ins. As you work through the tutorial, you will:
+Follow the tutorial to see how Angular makes browsers smarter — without the use of native
+extensions or plug-ins:
 
-* See examples of how to use client-side data binding and dependency injection to build dynamic
-views of data that change immediately in response to user actions.
-* See how Angular creates listeners on your data without the need for DOM manipulation.
-* Learn a better, easier way to test your web apps.
-* Learn how to use Angular services to make common web tasks, such as getting data into your app,
-easier.
+* See examples of how to use client-side data binding to build dynamic views of data that change
+  immediately in response to user actions.
+* See how Angular keeps your views in synch with your data without the need for DOM manipulation.
+* Learn a better, easier way to test your web apps, with Karma and Protractor.
+* Learn how to use dependency injection and services to make common web tasks, such as getting data
+  into your app, easier.
 
 When you finish the tutorial you will be able to:
 
 * Create a dynamic application that works in all modern browsers.
-* Define the differences between Angular and common JavaScript frameworks.
-* Understand how data binding works in AngularJS.
-* Create and run unit tests.
-* Create and run end to end tests.
+* Use data binding to wire up your data model to your views.
+* Create and run unit tests, with Karma.
+* Create and run end to end tests, with Protractor.
+* Move application logic out of the template and into Controllers.
+* Get data from a server using Angular services.
+* Apply animations to your application, using ngAnimate.
 * Identify resources for learning more about AngularJS.
 
 The tutorial guides you through the entire process of building a simple application, including
@@ -40,31 +42,46 @@ You can go through the whole tutorial in a couple of hours or you may want to sp
 really digging into it. If you're looking for a shorter introduction to AngularJS, check out the
 {@link misc/started Getting Started} document.
 
+# Get Started
 
+The rest of this page explains how you can set up your machine to work with the code on your local
+machine.  If you just want to read the tutorial then you can just go straight to the first step:
+[Step 0 - Bootstrapping](tutorial/step_00).
 
 # Working with the code
 
-You can follow along with this tutorial and hack on the code in either the Mac/Linux or the Windows
-environment. The tutorial relies on the use of the [Git][git] versioning system for source code
-management.
+You can follow along with this tutorial and hack on the code in the comfort of your own computer.
+In this way you can get hands-on practice of really writing AngularJS code and also on using the
+recommended testing tools.
+
+The tutorial relies on the use of the [Git][git] versioning system for source code management.
+You don't need to know anything about Git to follow the tutorial other than how to install and run
+a few git commands.
 
-You don't need to know anything about Git to follow the tutorial. Select one of the tabs below
-and follow the instructions for setting up your computer.
 
+### Install Git
 
-## Install Git
+You can download and install Git from http://git-scm.com/download. Once installed you should have
+access to the `git` command line tool.  The main commands that you will need to use are:
 
-You'll need Git, which you can get from [the Git site][git].
+- `git clone ...` : clone a remote repository onto your local machine
+- `git checkout ...` : check out a particular branch or a tagged version of the code to hack on
+
+### Download angular-phonecat
 
 Clone the [angular-phonecat repository][angular-phonecat] located at GitHub by running the following
 command:
 
 ```
-git clone https://github.com/angular/angular-phonecat.git
+git clone --depth=14 https://github.com/angular/angular-phonecat.git
 ```
 
 This command creates the `angular-phonecat` directory in your current directory.
 
+<div class="alert alert-info">The `--depth=14` option just tells Git to pull down only the last 14 commits.  This makes the
+download much smaller and faster.
+</div>
+
 Change your current directory to `angular-phonecat`.
 
 ```
@@ -75,118 +92,144 @@ The tutorial instructions, from now on, assume you are running all commands from
 `angular-phonecat` directory.
 
 
-## Install Node.js
-
-If you want to run the built-in web-server and the test tools then you will also need
-Node.js v0.10, or later.
+### Install Node.js
 
-You can download Node.js from the [node.js website][node].
+If you want to run the preconfigured local web-server and the test tools then you will also need
+[Node.js v0.10+][node].
 
+You can download a Node.js installer for your operating system from http://nodejs.org/download/.
 
-You can check the version of Node.js that you have installed by running the following command:
+Check the version of Node.js that you have installed by running the following command:
 
 ```
 node --version
 ```
 
-<div class="alert alert-info"><strong>Helpful note:<strong> If you need to run a different versions of node.js
+<div class="alert alert-info">If you need to run a different versions of node.js
   in your local environment, consider installing
   <a href="https://github.com/creationix/nvm" title="Node Version Manager Github Repo link">
     Node Version Manager (nvm)
   </a>.
 </div>
 
-Once you have Node.js installed you can install the tool dependencies by running:
+Once you have Node.js installed on your machine you can download the tool dependencies by running:
 
 ```
 npm install
 ```
 
-This command will download the following tools, into the `node_modules` directive:
+This command will download the following tools, into the `node_modules` directory:
 
 - [Bower][bower] - client-side code package manager
-- [http-server][http-server] - simple local static web server
+- [Http-Server][http-server] - simple local static web server
 - [Karma][karma] - unit test runner
-- [protractor][protractor] - end 2 end test runner
+- [Protractor][protractor] - end 2 end test runner
 
 Running `npm install` will also automatically run `bower install`, which will download the Angular
 framework into the `bower_components` directory.
 
 The project is preconfigured with a number of npm helper scripts to make it easy to run the common
-tasks that you will need while developing.
+tasks that you will need while developing:
+
+- `npm start` : start a local development web-server
+- `npm test` : start the Karma unit test runner
+- `npm run protractor` : run the Protractor end 2 end tests
+- `npm update-webdriver` : install the drivers needed by Protractor
 
-## Running Development Web Server
+### Running Development Web Server
 
-The project is preconfigured to provide a simple static web server for hosting the application.
-Start the web server by running:
+While Angular applications are purely client-side code, and it is possible to open them in a web
+browser directly from the file system, it is better to server them from a HTTP web server.  In
+particular, for security reasons, most modern browsers will not allow JavaScript to make server
+requests if the page is loaded directly from the file system.
+
+The angular-phonecat project is configured with a simple static web server for hosting the
+application during development. Start the web server by running:
 
 ```
 npm start
 ```
 
-Now you can browse to the application at:
+This will create a local webserver that is listening to port 8000 on your local machine.
+You can now browse to the application at:
 
 ```
 http://localhost:8000/app/index.html
 ```
 
-## Running Unit Tests
+### Running Unit Tests
+
+We use unit tests to ensure that the JavaScript code in our application is operating correctly.
+Unit tests focus on testing small isolated parts of the application. The unit tests are kept in the
+`test/unit` directory.
 
-The project is preconfigured to use [Karma][karma] to run the unit tests for the application.  Start
-Karma by running:
+The angular-phonecat project is configured to use [Karma][karma] to run the unit tests for the
+application.  Start Karma by running:
 
 ```
 npm test
 ```
 
-This will start the Karma unit test runner, open up a Chrome browser and execute all the unit tests
-in this browser. Karma will then sit and watch all the source and test JavaScript files.
-Whenever one of these files changes Karma re-runs all the unit tests.
+This will start the Karma unit test runner. Karma will read the configuration file at
+`test/karma.conf.js`.  This configuration file tells Karma to:
 
-It is good to leave this running all the time as you will get immediate feedback from Karma as you
-are working on the code.
+- open up a Chrome browser and connect it to Karma
+- execute all the unit tests in this browser
+- report the results of these tests in the terminal/command line window
+- watch all the project's JavaScript files and re-run the tests whenever any of these change
 
+It is good to leave this running all the time, in the background, as it will give you immediate
+feedback about whether your changes pass the unit tests while you are working on the code.
 
-## Running End to End Tests
 
-The project is preconfigured to use [Protractor][protractor] to run the end to end tests for the
-application. Set up the binaries protractor needs to run by running:
+### Running End to End Tests
 
-```
-npm run update-webdriver
-```
-(You will only need to do this once) Execute the Protractor test scripts against your application
-by running:
+We use End to End tests to ensure that the application as a whole operates as expected.
+End to End tests are designed to test the whole client side application, in particular that the
+views are displaying and behaving correctly. It does this by simulating real user interaction with
+the real application running in the browser.
+
+The End to End tests are kept in the `test/e2e` directory.
+
+The angular-phonecat project is configured to use [Protractor][protractor] to run the End to End
+tests for the application.  Protractor relies upon a set of drivers to allow it to interact with
+the browser. You can install these drivers by running:
 
 ```
-npm run protractor
+npm run update-webdriver
 ```
 
-This will start the Protractor end to end test runner, open up a Chrome browser and execute all the
-end to end test scripts in this browser. Once the test scripts finish, the browser will close down
-and Protractor will exit.
+*(You should only need to do this once.)*
 
-It is good to run the end to end tests whenever you make changes to the HTML views or want to check
-that the application as a whole is executing correctly.
+Since Protractor works by interacting with a running application, we need to start our web server:
 
-<div class="alert alert-info"><strong>Helpful note:</strong> Protractor requires that a web server is running
-  and serving up the application at the default URL: `http://localhost:8000/app/index.html`. You can
-  start the provided development server by running `npm start`.
-</div>
+```
+npm start
+```
 
+Then in a separate terminal/command line window, we can run the Protractor test scripts against the
+application by running:
 
-# Get Started
+```
+npm run protractor
+```
 
-Now your environment is ready, it is time to get started developing the Angular PhoneCat
-application.
+Protractor will read the configuration file at `test/protractor-conf.js`.  This configuration tells
+Protractor to:
 
-<a href="tutorial/step_00" title="Next Step"><span class="btn btn-primary">Step 0 - Bootstrapping</span></a>
+- open up a Chrome browser and connect it to the application
+- execute all the End to End tests in this browser
+- report the results of these tests in the terminal/command line window
+- close down the browser and exit
 
+It is good to run the end to end tests whenever you make changes to the HTML views or want to check
+that the application as a whole is executing correctly.  It is very common to run End to End tests
+before pushing a new commit of changes to a remote repository.
 
 
-[git]: http://git-scm.com/download
-[angular-phonecat]: https://github.com/angular/angular-phonecat
+[git]: http://git-scm.com/
 [node]: http://nodejs.org/
+[angular-phonecat]: https://github.com/angular/angular-phonecat
 [protractor]: https://github.com/angular/protractor
 [bower]: http://bower.io/
 [http-server]: https://github.com/nodeapps/http-server