From 3e54a1b18ab698d55e1642a120f95ea3adf6af1b Mon Sep 17 00:00:00 2001
From: Igor Minar
Date: Fri, 29 Jul 2011 12:40:14 -0700
Subject: doc(tutorial): fixes and improvements from Toni and Ben

---
 docs/content/tutorial/index.ngdoc   | 159 ++++++++++++++++++------------------
 docs/content/tutorial/step_00.ngdoc |  26 +++---
 docs/content/tutorial/step_01.ngdoc |   4 +-
 docs/content/tutorial/step_02.ngdoc |  82 ++++++++++---------
 docs/content/tutorial/step_03.ngdoc |  56 +++++++------
 docs/content/tutorial/step_04.ngdoc |  15 ++--
 docs/content/tutorial/step_05.ngdoc |   4 +-
 docs/content/tutorial/step_06.ngdoc |   8 +-
 docs/content/tutorial/step_07.ngdoc |  10 +--
 docs/content/tutorial/step_08.ngdoc |   4 +-
 docs/content/tutorial/step_09.ngdoc |   4 +-
 docs/content/tutorial/step_10.ngdoc |   4 +-
 docs/content/tutorial/step_11.ngdoc |   3 +-
 13 files changed, 196 insertions(+), 183 deletions(-)

(limited to 'docs/content')

diff --git a/docs/content/tutorial/index.ngdoc b/docs/content/tutorial/index.ngdoc
index 605bccd3..c26ea2df 100644
--- a/docs/content/tutorial/index.ngdoc
+++ b/docs/content/tutorial/index.ngdoc
@@ -2,40 +2,40 @@
 @name Tutorial
 @description
 
-A great way to get introduced to angular is to work through this tutorial, which walks you through
-the construction of an angular web app. The app you will build is a catalog that displays a list of
-Android devices, lets you filter the list to see only devices that interest you, and then view
+A great way to get introduced to Angular is to work through this tutorial, which walks you through
+the construction of an AngularJS web app. The app you will build is a catalog that displays a list
+of Android devices, lets you filter the list to see only devices that interest you, and then view
 details for any device.
 
 <img src="img/tutorial/catalog_screen.png">
 
-As you work through this tutorial, you will learn how angular makes browsers smarter — without the
-use of extensions or plugins.
+Work through the tutorial to see how Angular makes browsers smarter — without the use of extensions
+or plug-ins. As you work through the tutorial, you will:
 
-* You will 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.
-* You will see how angular creates listeners on your data without the need for DOM manipulation.
-* You will learn a better, easier way to test your web apps.
-* You will 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 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.
 
-And all of this works in any browser without modifications!
+And all of this works in any browser without modification to the browser!
 
 When you finish the tutorial you will be able to:
 
-* Create a dynamic application that works in any browser
-* Define the differences between angular and common JavaScript frameworks
-* Understand how data binding works in angular
-* Use the angular-seed project to quickly boot-strap your own projects
-* Create and run tests
-* Identify resources for learning more about angular
+* Create a dynamic application that works in any browser.
+* Define the differences between Angular and common JavaScript frameworks.
+* Understand how data binding works in AngularJS.
+* Use the angular-seed project to quickly boot-strap your own projects.
+* Create and run tests.
+* Identify resources for learning more about AngularJS.
 
-The tutorial is will guide you through the process of building a simple application, including
-writing and running unit and end-to-end tests, and will allow you to experiment with angular and
-the application through experiments suggested at the end of each step.
+The tutorial guides you through the entire process of building a simple application, including
+writing and running unit and end-to-end tests. Experiments at the end of each step provide
+suggestions for you learn more about AngularJS and the application you are building.
 
 You can go through the whole tutorial in a couple of hours or you may want to spend a pleasant day
-really digging into it. If you're looking for a shorter introduction to angular, check out the
+really digging into it. If you're looking for a shorter introduction to AngularJS, check out the
 {@link misc/started Getting Started} document.
 
 
@@ -46,11 +46,11 @@ really digging into it. If you're looking for a shorter introduction to angular,
 
 # Working with the code
 
-There are two ways that you can you follow this tutorial and hack on the code, both available on
-Mac/Linux or Windows environment. The first work flow uses Git versioning system for source code
-management, the second work flow doesn't depend on any source control system and instead uses
-scripts to copy snapshots of project files into your workspace (`sandbox`) directory. Choose the
-one you prefer:
+You can follow this tutorial and hack on the code in either the Mac/Linux or the Windows
+environment. Options for working with the tutorial are to use the Git versioning system for source
+code management or to use scripts that copy snapshots of project files into your workspace
+(`sandbox`) directory. Select one of the tabs below and follow the instructions for setting up your
+computer for your preferred option.
 
 <doc:tutorial-instructions show="true">
   <doc:tutorial-instruction id="git-mac" title="Git on Mac/Linux">
@@ -59,67 +59,68 @@ one you prefer:
 following command in a terminal window:</p>
       <pre><code>java -version</code></pre>
       <p>You will need Java to run unit tests.</p></li>
-      <li><p>Get Git from <a href="http://git-scm.com/download">here</a></p>
-      <p>You can build it from source or use pre-compiled package.</p></li>
+      <li><p>Download Git from the <a href="http://git-scm.com/download">Git</a> site.</p>
+      <p>You can build Git from source or use the pre-compiled package.</p></li>
       <li><p>Clone the angular-phonecat repository located at <a
-href="https://github.com/angular/angular-phonecat">Github</a> by running this command:</p>
+href="https://github.com/angular/angular-phonecat">Github</a> by running the following command:</p>
       <pre><code>git clone git://github.com/angular/angular-phonecat.git</code></pre>
-      <p>This will create <code>angular-phonecat</code> directory in current directory.</p></li>
+      <p>This command creates the <code>angular-phonecat</code> directory in your current
+directory.</p></li>
       <li><p>Change your current directory to <code>angular-phonecat</code>:</p>
       <pre><code>cd angular-phonecat</code></pre>
-      <p>The tutorial instructions assume you are running all commands from this directory.</p></li>
-      <li><p>You'll also need an http server running on your system. Mac and Linux machines
-typically have Apache preinstalled.</p>
-      <p>If you don't already have an http server installed, you can <a
+      <p>The tutorial instructions assume you are running all commands from the angular-phonecat
+directory.</p></li>
+      <li><p>You will need an http server running on your system. Mac and Linux machines typically
+have Apache pre-installed, but If you don't already have one installed, you can <a
 href="https://github.com/joyent/node/wiki/Installing-Node.js-via-package-manager">install
-node.js</a> and use it to run <code>scripts/web-server.js</code> — a simple bundled http
-server.</p></li>
+node.js</a>. Use <code>node</code> to run <code>scripts/web-server.js</code>,  a simple bundled
+http server.</p></li>
     </ol>
   </doc:tutorial-instruction>
 
   <doc:tutorial-instruction id="git-win" title="Git on Windows">
     <ol>
-      <li><p>Verify that you have <a href="http://java.com/">Java</a> installed and that the
-<code>java</code> executable is on your <code>PATH</code> by running this command in windows
-command line:</p>
+      <li><p>You will need Java to run unit tests, so run the following command to verify that you
+have <a href="http://java.com/">Java</a> installed and that the <code>java</code> executable is on
+your <code>PATH</code>.</p>
       <pre><code>java -version</code></pre>
-      <p>You will need Java to run unit tests.</p></li>
-      <li><p>Install msysGit from <a href="http://git-scm.com/download">here</a></p></li>
+      <p></p></li>
+      <li><p>Install msysGit from <a href="http://git-scm.com/download">the Git</a> site.</p></li>
       <li><p>Open msysGit bash and clone the angular-phonecat repository located at <a
-href="https://github.com/angular/angular-phonecat">Github</a> by running this command:</p>
+href="https://github.com/angular/angular-phonecat">Github</a> by running the following command:</p>
       <pre><code>git clone git://github.com/angular/angular-phonecat.git</code></pre>
-      <p>This will create angular-phonecat directory in your current directory.</p></li>
-      <li><p>Change your current directory to angular-phonecat:</p>
+      <p>This command creates the angular-phonecat directory in your current directory.</p></li>
+      <li><p>Change your current directory to angular-phonecat.</p>
       <pre><code>cd angular-phonecat</code></pre>
-      <p>The tutorial instructions assume you are running all commands from this directory.</p>
+      <p>The tutorial instructions assume you are running all commands from the angular-phonecat
+directory.</p>
       <p>You should run all <code>git</code> commands from msysGit bash.</p>
-      <p>Other commands like <code>test-server.bat</code> or <code>test.bat</code> that will be
-introduced soon, should be executed from the windows command line.</li>
-      <li><p>You'll also need an http server running on your system.</p>
-      <p>If you don't already have an http server installed, you can install <a
-href="http://nodejs.org/">node.js</a>. Just download <a
-href="http://node-js.prcn.co.cc/">pre-compiled binaries</a>, unzip them and add
-<code>nodejs\bin</code> into your <code>PATH</code> and use <code>node</code> to run
-<code>scripts\web-server.js</code> — a simple bundled http server.</p></li>
+      <p>Other commands like <code>test-server.bat</code> or <code>test.bat</code> should be
+executed from the Windows command line.</li>
+      <li><p>You need an http server running on your system. If you don't already have one
+installed, you can install <a href="http://nodejs.org/">node.js</a>. Download the <a
+href="http://node-js.prcn.co.cc/">pre-compiled binaries</a>, unzip them, and then add
+<code>nodejs\bin</code> into your <code>PATH</code>. Use <code>node</code> to run
+<code>scripts\web-server.js</code>, a simple, bundled http server.</p></li>
     </ol>
   </doc:tutorial-instruction>
 
   <doc:tutorial-instruction id="ss-mac" title="Snapshots on Mac/Linux">
     <ol>
-      <li><p>Verify that you have <a href="http://java.com/">Java</a> installed by running the
-following command in a terminal window:</p>
+      <li><p>You need Java to run unit tests, so verify that you have <a
+href="http://java.com/">Java</a> installed by running the following command in a terminal
+window:</p>
       <pre><code>java -version</code></pre>
-      <p>You will need Java to run unit tests.</p></li>
-      <li><p>Download the <a href="http://code.angularjs.org/angular-phonecat/">zip archive</a>
-with all files and unzip them into [tutorial-dir] directory</p></li>
-      <li><p>Change your current directory to [tutorial-dir]/sanbox:</p>
+       <li><p>Download the <a href="http://code.angularjs.org/angular-phonecat/">zip archive</a>
+containing all of the files and unzip them into the [tutorial-dir] directory</p>.</li>
+      <li><p>Change your current directory to [tutorial-dir]/sandbox, as follows:</p>
       <pre><code>cd [tutorial-dir]/sandbox</code></pre>
-      <p>The tutorial instructions assume you are running all commands from this directory.</p></li>
-      <li><p>You'll also need an http server running on your system. Mac and Linux machines
-typically have Apache preinstalled.</p>
-      <p>If you don't already have an http server installed, you can <a
+      <p>The tutorial instructions assume you are running all commands from your
+<code>sandbox</code> directory.</p></li>
+      <li><p>You need an http server running on your system and Mac and Linux machines typically
+have Apache pre-installed. If you don't have an http server installed, you can <a
 href="https://github.com/joyent/node/wiki/Installing-Node.js-via-package-manager">install
-node.js</a> and use it to run <code>scripts/web-server.js</code> — a simple bundled http
+node.js</a> and use it to run <code>scripts/web-server.js</code>, a simple bundled http
 server.</p></li>
     </ol>
   </doc:tutorial-instruction>
@@ -127,25 +128,23 @@ server.</p></li>
   <doc:tutorial-instruction id="ss-win" title="Snapshots on Windows">
     <ol>
       <li><p>Verify that you have <a href="http://java.com/">Java</a> installed and that the
-<code>java</code> executable is on your <code>PATH</code> by running this command in windows
-command line:</p>
+<code>java</code> executable is on your <code>PATH</code> by running the following command in the
+Windows command line:</p>
       <pre><code>java -version</code></pre>
-      <p>You will need Java to run unit tests.</p></li>
-      <li><p>Download the <a href="http://code.angularjs.org/angular-phonecat/">zip archive</a>
-with all files and unzip them into [tutorial-dir] directory</p></li>
-      <li><p>Change your current directory to [tutorial-dir]/sanbox:</p>
+      <p>You need Java to run unit tests, so download the <a
+href="http://code.angularjs.org/angular-phonecat/">zip archive</a> that contains all of the files
+and unzip the files into the [tutorial-dir] directory</p></li>
+      <li><p>Change your current directory to [tutorial-dir]/sandbox, as follows:</p>
       <pre><code>cd [tutorial-dir]/sandbox</code></pre>
       <p>The tutorial instructions assume you are running all commands from this directory.</p></li>
-      <li><p>You'll also need an http server running on your system.</p>
-      <p>If you don't already have an http server installed, you can install <a
-href="http://nodejs.org/">node.js</a>. Just download <a
-href="http://node-js.prcn.co.cc/">pre-compiled binaries</a>, unzip them and add
-<code>nodejs\bin</code> into your <code>PATH</code> and use <code>node</code> to run
-<code>scripts\web-server.js</code> — a simple bundled http server.</p></li>
+      <li><p>You need an http server running on your system, but if you don't already have one
+already installed, you can install <a href="http://nodejs.org/">node.js</a>. Download the <a
+href="http://node-js.prcn.co.cc/">pre-compiled binaries</a>, unzip them, and then add
+<code>nodejs\bin</code> into your <code>PATH</code>. Use <code>node</code> to run
+<code>scripts\web-server.js</code>, a simple bundled http server.</p></li>
     </ol>
   </doc:tutorial-instruction>
 </doc:tutorial-instructions>
 
-For either work flow you'll also need a web browser and your favorite text editor.
-
-Let's get going with {@link step_00 step 0}.
+The last thing to do is to make sure your computer has a web browser and a good text editor
+installed. Now, let's get going with {@link step_00 step 0}.
diff --git a/docs/content/tutorial/step_00.ngdoc b/docs/content/tutorial/step_00.ngdoc
index a8243d47..b1bdf628 100644
--- a/docs/content/tutorial/step_00.ngdoc
+++ b/docs/content/tutorial/step_00.ngdoc
@@ -5,8 +5,8 @@
 <ul doc:tutorial-nav="0"></ul>
 
 
-You are now ready to build the phonecat application. In this step, you will become familiar with
-the most important source code files, learn how to start the development servers bundled with
+You are now ready to build the Angular phonecat application. In this step, you will become familiar
+with the most important source code files, learn how to start the development servers bundled with
 angular-seed, and run the application in the browser.
 
 
@@ -78,7 +78,7 @@ directory.</li>
 
   <doc:tutorial-instruction id="ss-mac" title="Snapshots on Mac/Linux">
     <ol>
-      <li><p>In angular-phonecat directory, run this command:</p>
+      <li><p>In the angular-phonecat directory, run this command:</p>
       <pre><code>./goto_step.sh 0</code></pre>
       <p>This resets your workspace to step 0 of the tutorial app.</p>
       <p>You must repeat this for every future step in the tutorial and change the number to
@@ -110,7 +110,7 @@ href="http://localhost:8000/app/index.html">http://localhost:8000/app/index.html
 
   <doc:tutorial-instruction id="ss-win" title="Snapshots on Windows">
     <ol>
-      <li><p>Open windows command line and run this command (in angular-phonecat directory):</p>
+      <li><p>Open windows command line and run this command (in the angular-phonecat directory):</p>
       <pre><code>goto_step.bat 0</code></pre>
       <p>This resets your workspace to step 0 of the tutorial app.</p>
       <p>You must repeat this for every future step in the tutorial and change the number to
@@ -144,7 +144,7 @@ href="http://localhost:8000/app/index.html">http://localhost:8000/app/index.html
 You can now see the page in your browser. It's not very exciting, but that's OK.
 
 The static HTML page that displays "Nothing here yet!" was constructed with the HTML code shown
-below. The code contains some key angular elements that we will need going forward.
+below. The code contains some key Angular elements that we will need going forward.
 
 __`app/index.html`:__
 <pre>
@@ -172,25 +172,25 @@ __`app/index.html`:__
 
           <html xmlns:ng="http://angularjs.org">
 
-  This `xmlns` declaration for the `ng` namespace must be specified in all angular applications in
-order to make angular work with XHTML and IE versions older than 9 (regardless of whether you are
+  This `xmlns` declaration for the `ng` namespace must be specified in all Angular applications in
+order to make Angular work with XHTML and IE versions older than 9 (regardless of whether you are
 using XHTML or HTML).
 
-* angular script tag
+* Angular script tag
 
           <script src="lib/angular/angular.js" ng:autobind>
 
   This single line of code is all that is needed to bootstrap an angular application.
 
   The code downloads the `angular.js` script and registers a callback that will be executed by the
-browser when the containing HTML page is fully downloaded. When the callback is executed, angular
-looks for the {@link api/angular.directive.ng:autobind ng:autobind} attribute. If angular finds
+browser when the containing HTML page is fully downloaded. When the callback is executed, Angular
+looks for the {@link api/angular.directive.ng:autobind ng:autobind} attribute. If Angular finds
 `ng:autobind`, it creates a root scope for the application and associates it with the `<html>`
 element of the template:
 
   <img src="img/tutorial/tutorial_00_final.png">
 
-    As you will see shortly, everything in angular is evaluated within a scope. We'll learn more
+    As you will see shortly, everything in Angular is evaluated within a scope. We'll learn more
 about this in the next steps.
 
 
@@ -198,7 +198,7 @@ about this in the next steps.
 
 Most of the files in your working directory come from the {@link
 https://github.com/angular/angular-seed angular-seed project} which is typically used to bootstrap
-new angular projects. The seed project includes the latest angular libraries, test libraries,
+new Angular projects. The seed project includes the latest Angular libraries, test libraries,
 scripts and a simple example app, all pre-configured for developing a typical web app.
 
 For the purposes of this tutorial, we modified the angular-seed with the following changes:
@@ -210,7 +210,7 @@ For the purposes of this tutorial, we modified the angular-seed with the followi
 
 # Summary
 
-Now let's go to step 1 and add some content to the web app.
+Now let's go to {@link step_01 step 1} and add some content to the web app.
 
 
 <ul doc:tutorial-nav="0"></ul>
diff --git a/docs/content/tutorial/step_01.ngdoc b/docs/content/tutorial/step_01.ngdoc
index 37d7e0a6..fb8eb26e 100644
--- a/docs/content/tutorial/step_01.ngdoc
+++ b/docs/content/tutorial/step_01.ngdoc
@@ -50,8 +50,8 @@ __`app/index.html`:__
 
 # Summary
 
-This addition to your app uses static HTML to display the list. Now, let's go to step 2 to learn
-how to use angular to dynamically generate the same list.
+This addition to your app uses static HTML to display the list. Now, let's go to {@link step_02
+step 2} to learn how to use angular to dynamically generate the same list.
 
 
 <ul doc:tutorial-nav="1"></ul>
diff --git a/docs/content/tutorial/step_02.ngdoc b/docs/content/tutorial/step_02.ngdoc
index abed3977..4e1abfad 100644
--- a/docs/content/tutorial/step_02.ngdoc
+++ b/docs/content/tutorial/step_02.ngdoc
@@ -1,23 +1,23 @@
 @ngdoc overview
-@name Tutorial: 2 - Angular Template
+@name Tutorial: 2 - Angular Templates
 @description
 
 <ul doc:tutorial-nav="2"></ul>
 
 
-Now it's time to make this web page dynamic with angular. We'll also add a test that verifies the
+Now it's time to make the web page dynamic -- with Angular. We'll also add a test that verifies the
 code for the controller we are going to add.
 
-There are many ways to structure the code for an application. With angular, we encourage the use of
-{@link http://en.wikipedia.org/wiki/Model–View–Controller the MVC design pattern} to decouple the
-code and separate concerns. With that in mind, let's use a little angular and JavaScript to add
-model, view, and controller components to our app.
+There are many ways to structure the code for an application. For Angular apps, we encourage the
+use of {@link http://en.wikipedia.org/wiki/Model–View–Controller the Model-View-Controller (MVC)
+design pattern} to decouple the code and to separate concerns. With that in mind, let's use a
+little Angular and JavaScript to add model, view, and controller components to our app.
 
 
 <doc:tutorial-instructions step="2"></doc:tutorial-instructions>
 
 
-The app now contains a list with 3 phones.
+The app now contains a list with three phones.
 
 The most important changes are listed below. You can see the full diff on {@link
 https://github.com/angular/angular-phonecat/compare/step-1...step-2 GitHub}:
@@ -25,7 +25,7 @@ https://github.com/angular/angular-phonecat/compare/step-1...step-2 GitHub}:
 
 ## Template for the View
 
-The __view__ component is constructed by angular from this template:
+The __view__ component is constructed by Angular from this template:
 
 __`app/index.html`:__
 <pre>
@@ -46,22 +46,24 @@ __`app/index.html`:__
 </pre>
 
 We replaced the hard-coded phone list with the {@link api/angular.widget.@ng:repeat ng:repeat
-widget} and two {@link guide/dev_guide.expressions angular expressions} enclosed in curly braces:
+widget} and two {@link guide/dev_guide.expressions Angular expressions} enclosed in curly braces:
 `{{phone.name}}` and `{{phone.snippet}}`:
 
-* The `ng:repeat="phone in phones"` statement in the `<li>` tag is an angular repeater.  It tells
-angular to create a `<li>` element for each phone in the phones list, using the first `<li>` tag as
-the template.
+* The `ng:repeat="phone in phones"` statement in the `<li>` tag is an Angular repeater. The
+repeater tells Angular to create a `<li>` element for each phone in the list using the first `<li>`
+tag as the template.
 
       <img src="img/tutorial/tutorial_02_final.png">
 
-* The curly braces around `phone.name` and `phone.snippet` are an example of {@link
-guide/dev_guide.compiler.markup angular markup}. The curly markup is shorthand for the angular
-directive {@link api/angular.directive.ng:bind ng:bind}. The `ng:bind` directives indicate to
-angular that these are template binding points. Binding points are locations in the template where
-angular creates data-binding between the view and the model. In angular, the view is a projection
-of the model through the HTML template. This means that whenever the model changes, angular
-refreshes the appropriate binding points, which updates the view.
+* The curly braces around `phone.name` and `phone.snippet` are examples of {@link
+guide/dev_guide.compiler.markup Angular markup}. The curly markup is shorthand for the Angular
+directive {@link api/angular.directive.ng:bind ng:bind}. An `ng:bind` directive indicates a
+template binding point to Angular. Binding points are locations in a template where Angular creates
+data-binding between the view and the model.
+
+In Angular, the view is a projection of the model through the HTML template. This means that
+whenever the model changes, Angular refreshes the appropriate binding points, which updates the
+view.
 
 
 ## Model and Controller
@@ -86,26 +88,27 @@ function PhoneListCtrl() {
 
 Although the controller is not yet doing very much controlling, it is playing a crucial role. By
 providing context for our data model, the controller allows us to establish data-binding between
-the model and the view. Note in the following how we connected the dots between our presentation,
-data, and logic components:
+the model and the view. We connected the dots between the presentation, data, and logic components
+as follows:
 
 * The name of our controller function (in the JavaScript file `controllers.js`) matches the {@link
 api/angular.directive.ng:controller ng:controller} directive in the `<body>` tag (`PhoneListCtrl`).
-* We instantiated our data within the scope of our controller function, and our template binding
+* The data is instantiated within the *scope* of our controller function; our template binding
 points are located within the block bounded by the `<body ng:controller="PhoneListCtrl">` tag.
 
-Angular scopes are a crucial concept in angular; you can think of scopes as the glue that makes the
-template, model and controller all work together. Angular uses scopes, along with the information
-contained in the template, data model, and controller, to keep the model and view separated but in
-sync. Any changes to the model are reflected in the view; any changes that occur in the view are
-reflected in the model. To learn more about angular scopes, see the {@link api/angular.scope
-angular scope documentation}.
+  The concept of a scope in Angular is crucial; a scope can be seen as the glue which allows the
+template, model and controller to work together. Angular uses scopes, along with the information
+contained in the template, data model, and controller, to keep models and views separate, but in
+sync. Any changes made to the model are reflected in the view; any changes that occur in the view
+are reflected in the model.
+
+  To learn more about Angular scopes, see the {@link api/angular.scope angular scope documentation}.
 
 
 ## Tests
 
-The "Angular way" makes it easy for us to test as we develop; the unit test for your newly created
-controller looks as follows:
+The "Angular way" makes it easy to test code as it is being developed. Take a look at the following
+unit test for your newly created controller:
 
 __`test/unit/controllersSpec.js`:__
 <pre>
@@ -121,14 +124,16 @@ describe('PhoneCat controllers', function() {
 });
 </pre>
 
-Ease of testing is another cornerstone of angular's design philosophy. All we are doing here is
-showing how easy it is to create a unit test. The test verifies that we have 3 records in the
-phones array.
+The test verifies that we have three records in the phones array and the example demonstrates how
+easy it is to create a unit test for code in Angular. Since testing is such a critical part of
+software development, we make it easy to create tests in Angular so that developers are encouraged
+to write them.
 
 Angular developers prefer the syntax of Jasmine's Behavior-driven Development  (BDD) framework when
-writing tests. Although Jasmine is not required by angular, we used it to write all tests in this
-tutorial. You can learn about Jasmine on the {@link http://pivotal.github.com/jasmine/ Jasmine home
-page} and on the {@link https://github.com/pivotal/jasmine/wiki Jasmine wiki}.
+writing tests. Although Angular does not require you to use Jasmine, we wrote all of the tests in
+this tutorial in Jasmine. You can learn about Jasmine on the {@link
+http://pivotal.github.com/jasmine/ Jasmine home page} and on the {@link
+https://github.com/pivotal/jasmine/wiki Jasmine wiki}.
 
 The angular-seed project is pre-configured to run all unit tests using {@link
 http://code.google.com/p/js-test-driver/ JsTestDriver}. To run the test, do the following:
@@ -189,8 +194,9 @@ and kill the script, then repeat the procedure above.
 
 # Summary
 
-You now have a dynamic app that features separate model, view, and controller components, and
-you're testing as you go. Now, let's go to step 3 to learn how to add full text search to the app.
+You now have a dynamic app that features separate model, view, and controller components, and you
+are testing as you go. Now, let's go to {@link step_03 step 3} to learn how to add full text search
+to the app.
 
 
 <ul doc:tutorial-nav="2"></ul>
diff --git a/docs/content/tutorial/step_03.ngdoc b/docs/content/tutorial/step_03.ngdoc
index 1ebde553..ec546956 100644
--- a/docs/content/tutorial/step_03.ngdoc
+++ b/docs/content/tutorial/step_03.ngdoc
@@ -6,19 +6,19 @@
 
 
 We did a lot of work in laying a foundation for the app in the last step, so now we'll do something
-simple, and add full text search (yes, it will be simple!). We will also write an end-to-end test,
-because a good end-to-end test is a good friend. It stays with your app, keeps an eye on it, and
-quickly detects regressions.
+simple; we will add full text search (yes, it will be simple!). We will also write an end-to-end
+test, because a good end-to-end test is a good friend. It stays with your app, keeps an eye on it,
+and quickly detects regressions.
 
 
 <doc:tutorial-instructions step="3"></doc:tutorial-instructions>
 
 
-The app now has a search box. The phone list on the page changes depending on what a user types
-into the search box.
+The app now has a search box. Notice that the phone list on the page changes depending on what a
+user types into the search box.
 
-The most important changes are listed below. You can see the full diff on {@link
-https://github.com/angular/angular-phonecat/compare/step-2...step-3
+The most important differences between Steps 2 and 3 are listed below. You can see the full diff on
+{@link https://github.com/angular/angular-phonecat/compare/step-2...step-3
  GitHub}:
 
 
@@ -43,13 +43,13 @@ __`app/index.html`:__
 ...
 </pre>
 
-We added a standard HTML `<input>` tag and use angular's {@link api/angular.Array.filter $filter}
+We added a standard HTML `<input>` tag and used angular's {@link api/angular.Array.filter $filter}
 function to process the input for the `ng:repeater`.
 
 This lets a user enter search criteria and immediately see the effects of their search on the phone
-list.  This new code demonstrates the following:
+list. This new code demonstrates the following:
 
-* Data-binding. This is one of the core features in angular. When the page loads, angular binds the
+* Data-binding. This is one of the core features in Angular. When the page loads, Angular binds the
 name of the input box to a variable of the same name in the data model and keeps the two in sync.
 
   In this code, the data that a user types into the input box (named __`query`__) is immediately
@@ -59,7 +59,7 @@ the DOM to reflect the current state of the model.
 
       <img src="img/tutorial/tutorial_03_final.png">
 
-* Use of `$filter`. The {@link api/angular.Array.filter $filter} method, uses the `query` value, to
+* Use of `$filter`. The {@link api/angular.Array.filter $filter} method uses the `query` value to
 create a new array that contains only those records that match the `query`.
 
   `ng:repeat` automatically updates the view in response to the changing number of phones returned
@@ -67,7 +67,7 @@ by the `$filter`. The process is completely transparent to the developer.
 
 ## Test
 
-In step 2, we learned how to write and run unit tests. Unit tests are perfect for testing
+In Step 2, we learned how to write and run unit tests. Unit tests are perfect for testing
 controllers and other components of our application written in JavaScript, but they can't easily
 test DOM manipulation or the wiring of our application. For these, an end-to-end test is a much
 better choice.
@@ -101,9 +101,9 @@ describe('PhoneCat App', function() {
 Even though the syntax of this test looks very much like our controller unit test written with
 Jasmine, the end-to-end test uses APIs of {@link
 https://docs.google.com/document/d/11L8htLKrh6c92foV71ytYpiKkeKpM4_a5-9c3HywfIc/edit?hl=en&pli=1#
-angular's end-to-end test runner}.
+Angular's end-to-end test runner}.
 
-To run the end-to-end test, open the following in a new browser tab:
+To run the end-to-end test, open one of the following in a new browser tab:
 
 * node.js users: {@link http://localhost:8000/test/e2e/runner.html}
 * users with other http servers:
@@ -111,7 +111,7 @@ To run the end-to-end test, open the following in a new browser tab:
 * casual reader: {@link http://angular.github.com/angular-phonecat/step-3/test/e2e/runner.html}
 
 This test verifies that the search box and the repeater are correctly wired together. Notice how
-easy it is to write end-to-end tests in angular. Although this example is for a simple test, it
+easy it is to write end-to-end tests in Angular. Although this example is for a simple test, it
 really is that easy to set up any functional, readable, end-to-end test.
 
 # Experiments
@@ -138,6 +138,14 @@ and title elements:
 
   Be sure to *remove* the `ng:controller` declaration from the body element.
 
+  While using double curlies works fine in within the title element, you might have noticed that
+for a split second they are actually displayed to the user while the page is loading. A better
+solution would be to use the {@link api/angular.directive.ng:bind ng:bind} or {@link
+api/angular.directive.ng:bind-template ng:bind-template} directives, which are invisible to the
+user while the page is loading:
+
+          <title ng:bind-template="Google Phone Gallery: {{query}}">Google Phone Gallery</title>
+
 * Add the following end-to-end test into the `describe` block within `test/e2e/scenarios.js`:
 
   <pre>
@@ -154,20 +162,20 @@ and title elements:
     });
   </pre>
 
-  Refresh the browser tab with end-to-end test runner to see the test fail. Now add a `div` or `p`
-element with `id` `"status"` and content with the `query` binding into the `index.html` template to
-make the test pass.
+  Refresh the browser tab with the end-to-end test runner to see the test fail. To make the test
+pass, edit the `index.html` template to add a `div` or `p` element with `id` `"status"` and content
+with the `query` binding.
 
-* Add a `pause()` statement into an end-to-end test and rerun it.  You'll see the runner pausing,
-giving you the opportunity to explore the state of your application displayed in the browser. The
-app is live! Change the search query to prove it. This is great for troubleshooting end-to-end
-tests.
+* Add a `pause()` statement into an end-to-end test and rerun it. You'll see the runner pause; this
+gives you the opportunity to explore the state of your application while it is displayed in the
+browser. The app is live! You can change the search query to prove it. Notice how useful this is
+for troubleshooting end-to-end tests.
 
 
 # Summary
 
-With full text search under our belt and a test to verify it, let's go to step 4 to learn how to
-add sorting capability to the phone app.
+We have now added full text search and included a test to verify that search works! Now let's go on
+to {@link step_04 step 4} to learn how to add sorting capability to the phone app.
 
 
 <ul doc:tutorial-nav="3"></ul>
diff --git a/docs/content/tutorial/step_04.ngdoc b/docs/content/tutorial/step_04.ngdoc
index 48084980..72aa26c9 100644
--- a/docs/content/tutorial/step_04.ngdoc
+++ b/docs/content/tutorial/step_04.ngdoc
@@ -16,9 +16,8 @@ the repeater, and letting the data binding magic do the rest of the work.
 You should see that in addition to the search box, the app displays a drop down menu that allows
 users to control the order in which the phones are listed.
 
-The most important changes are listed below. You can see the full diff on {@link
-https://github.com/angular/angular-phonecat/compare/step-3...step-4
-GitHub}:
+The most important differences between Steps 3 and 4 are listed below. You can see the full diff on
+{@link https://github.com/angular/angular-phonecat/compare/step-3...step-4 GitHub}:
 
 
 ## Template
@@ -48,7 +47,7 @@ __`app/index.html`:__
 ...
 </pre>
 
-In the `index.html` template we made the following changes:
+We made the following changes to the `index.html` template:
 
 * First, we added a `<select>` html element named `orderProp`, so that our users can pick from the
 two provided sorting options.
@@ -63,7 +62,7 @@ Angular creates a two way data-binding between the select element and the `order
 `orderProp` is then used as the input for the `$orderBy` method.
 
 As we discussed in the section about data-binding and the repeater in step 3, whenever the model
-changes (for example because a user changes the order with the select drop down menu), angular's
+changes (for example because a user changes the order with the select drop down menu), Angular's
 data-binding will cause the view to automatically update. No bloated DOM manipulation code is
 necessary!
 
@@ -179,7 +178,7 @@ The end-to-end test verifies that the ordering mechanism of the select box is wo
 You can now refresh the browser tab with the end-to-end test runner to see the tests run, or you
 can see them running on {@link
 http://angular.github.com/angular-phonecat/step-4/test/e2e/runner.html
-angular's server}.
+Angular's server}.
 
 # Experiments
 
@@ -192,8 +191,8 @@ text.
 
 # Summary
 
-Now that you have added list sorting and tested the app, go to step 5 to learn about angular
-services and how angular uses dependency injection.
+Now that you have added list sorting and tested the app, go to {@link step_05 step 5} to learn
+about Angular services and how Angular uses dependency injection.
 
 
 <ul doc:tutorial-nav="4"></ul>
diff --git a/docs/content/tutorial/step_05.ngdoc b/docs/content/tutorial/step_05.ngdoc
index 1aac51f7..fd8f19b8 100644
--- a/docs/content/tutorial/step_05.ngdoc
+++ b/docs/content/tutorial/step_05.ngdoc
@@ -209,8 +209,8 @@ to the first 5 in the list. Use the following code in the xhr callback:
 # Summary
 
 Now that you have learned how easy it is to use angular services (thanks to angular's
-implementation of dependency injection), go to step 6, where you will add some thumbnail images of
-phones and some links.
+implementation of dependency injection), go to {@link step_06 step 6}, where you will add some
+thumbnail images of phones and some links.
 
 
 <ul doc:tutorial-nav="5"></ul>
diff --git a/docs/content/tutorial/step_06.ngdoc b/docs/content/tutorial/step_06.ngdoc
index aa628a5d..45e667de 100644
--- a/docs/content/tutorial/step_06.ngdoc
+++ b/docs/content/tutorial/step_06.ngdoc
@@ -58,11 +58,11 @@ __`app/index.html`:__
 To dynamically generate links that will in the future lead to phone detail pages, we used the
 now-familiar {@link guide/dev_guide.compiler.markup double-curly brace markup} in the `href`
 attribute values. In step 2, we added the `{{phone.name}}` binding as the element content. In this
-step the '{{phone.id}}' binding is used in the element attribute.
+step the `{{phone.id}}` binding is used in the element attribute.
 
 We also added phone images next to each record using an image tag with the {@link
 api/angular.directive.ng:src ng:src} directive. That directive prevents the browser from treating
-the angular `{{ exppression }}` markup literally, which it would have done if we had only specified
+the angular `{{ expression }}` markup literally, which it would have done if we had only specified
 an attribute binding in a regular `src` attribute (`<img src="{{phone.imageUrl}}">`). Using
 `ng:src` prevents the browser from making an http request to an invalid location.
 
@@ -98,8 +98,8 @@ making an extraneous request to `/app/%7B%7Bphone.imageUrl%7D%7D` (or
 
 # Summary
 
-Now that you have added phone images and links, go to step 7 to learn about angular layout
-templates and how angular makes it easy to create applications that have multiple views.
+Now that you have added phone images and links, go to {@link step_07 step 7} to learn about angular
+layout templates and how angular makes it easy to create applications that have multiple views.
 
 
 <ul doc:tutorial-nav="6"></ul>
diff --git a/docs/content/tutorial/step_07.ngdoc b/docs/content/tutorial/step_07.ngdoc
index 4f6a768e..0f5fdda2 100644
--- a/docs/content/tutorial/step_07.ngdoc
+++ b/docs/content/tutorial/step_07.ngdoc
@@ -68,8 +68,8 @@ function PhoneCatCtrl($route) {
 We created a new controller called `PhoneCatCtrl`. We declared its dependency on the `$route`
 service and used this service to declare that our application consists of two different views:
 
-* The phone list view will be shown when the URL hash fragment is `/phone`. To construct this view,
-angular will use the `phone-list.html` template and the `PhoneListCtrl` controller.
+* The phone list view will be shown when the URL hash fragment is `/phones`. To construct this
+view, angular will use the `phone-list.html` template and the `PhoneListCtrl` controller.
 
 * The phone details view will be shown when the URL hash fragment matches '/phone/:phoneId', where
 `:phoneId` is a variable part of the URL. To construct the phone details view, angular will use the
@@ -151,7 +151,7 @@ __`app/partials/phone-list.html`:__
 TBD: detail view for {{params.phoneId}}
 </pre>
 
-Note how we are using `params` model defined in the `PhoneCanCtrl` controller.
+Note how we are using `params` model defined in the `PhoneCatCtrl` controller.
 
 
 ## Test
@@ -202,8 +202,8 @@ inheritance and model property shadowing do some wonders.
 
 # Summary
 
-With the routing set up and the phone list view implemented, we're ready to go to step 8 to
-implement the phone details view.
+With the routing set up and the phone list view implemented, we're ready to go to {@link step_08
+step 8} to implement the phone details view.
 
 
 <ul doc:tutorial-nav="7"></ul>
diff --git a/docs/content/tutorial/step_08.ngdoc b/docs/content/tutorial/step_08.ngdoc
index e81a8d93..ef55885f 100644
--- a/docs/content/tutorial/step_08.ngdoc
+++ b/docs/content/tutorial/step_08.ngdoc
@@ -181,8 +181,8 @@ Nexus S details page.
 
 # Summary
 
-Now that the phone details view is in place, proceed to step 9 to learn how to write your own
-custom display filter.
+Now that the phone details view is in place, proceed to {@link step_09 step 9} to learn how to
+write your own custom display filter.
 
 
 <ul doc:tutorial-nav="8"></ul>
diff --git a/docs/content/tutorial/step_09.ngdoc b/docs/content/tutorial/step_09.ngdoc
index 4aa5c56b..80b10f65 100644
--- a/docs/content/tutorial/step_09.ngdoc
+++ b/docs/content/tutorial/step_09.ngdoc
@@ -114,8 +114,8 @@ the following to index.html:
 
 # Summary
 
-Now that you have learned how to write and test a custom filter, go to step 10 to learn how we can
-use angular to enhance the phone details page further.
+Now that you have learned how to write and test a custom filter, go to {@link step_10 step 10} to
+learn how we can use angular to enhance the phone details page further.
 
 
 <ul doc:tutorial-nav="9"></ul>
diff --git a/docs/content/tutorial/step_10.ngdoc b/docs/content/tutorial/step_10.ngdoc
index b4f0370d..73e8b354 100644
--- a/docs/content/tutorial/step_10.ngdoc
+++ b/docs/content/tutorial/step_10.ngdoc
@@ -133,8 +133,8 @@ template remains operational.
 
 # Summary
 
-With the phone image swapper in place, we're ready for step 11 (the last step!) to learn an even
-better way to fetch data.
+With the phone image swapper in place, we're ready for {@link step_11 step 11} (the last step!) to
+learn an even better way to fetch data.
 
 
 <ul doc:tutorial-nav="10"></ul>
diff --git a/docs/content/tutorial/step_11.ngdoc b/docs/content/tutorial/step_11.ngdoc
index e328aecd..b67694f4 100644
--- a/docs/content/tutorial/step_11.ngdoc
+++ b/docs/content/tutorial/step_11.ngdoc
@@ -201,7 +201,8 @@ output.
 
 # Summary
 
-There you have it!  We have created a web app in a relatively short amount of time.
+There you have it!  We have created a web app in a relatively short amount of time. In the {@link
+the_end closing notes} we'll cover were to go from here.
 
 
 <ul doc:tutorial-nav="11"></ul>
-- 
cgit v1.2.3