From f34cecd3e54250038df29187fb4a3013030ad896 Mon Sep 17 00:00:00 2001
From: Carol Franger <cfranger@gmail.com>
Date: Fri, 21 Oct 2016 13:07:41 -0700
Subject: [PATCH 1/5] Initial edits with several questions for Naomi and Ward.

---
 public/docs/ts/latest/tutorial/toh-pt1.jade | 121 +++++++++++---------
 1 file changed, 64 insertions(+), 57 deletions(-)

diff --git a/public/docs/ts/latest/tutorial/toh-pt1.jade b/public/docs/ts/latest/tutorial/toh-pt1.jade
index dfc137c3b8..01b08673a9 100644
--- a/public/docs/ts/latest/tutorial/toh-pt1.jade
+++ b/public/docs/ts/latest/tutorial/toh-pt1.jade
@@ -3,16 +3,14 @@ include ../_util-fns
 :marked
   # Once Upon a Time
 
-  Every story starts somewhere. Our story starts where the [QuickStart](../quickstart.html) ends.
+  Run the <live-example></live-example>.
 
-  Run the <live-example></live-example> for this part.
-
-  Create a folder called `angular-tour-of-heroes` and follow the [QuickStart](../quickstart.html) steps
-  which provide the prerequisites, the folder structure, and the core files for our Tour of Heroes.
+  Create a folder called `angular-tour-of-heroes` and follow the [QuickStart](../quickstart.html) steps,
+  which provide the prerequisites, folder structure, and core files for the Tour of Heroes.
 
 include ../_quickstart_repo
 :marked
-  We should have the following structure:
+  You should have the following structure:
 
 .filetree
   .file angular-tour-of-heroes
@@ -32,34 +30,36 @@ include ../_quickstart_repo
     .file typings.json
 :marked
   ## Keep the app transpiling and running
-  We want to start the TypeScript compiler, have it watch for changes, and start our server. We'll do this by typing
+  Type the following command:
 
 code-example(language="bash").
   npm start
 
 :marked
   This command runs the compiler in watch mode, starts the server, launches the app in a browser,
-  and keeps the app running while we continue to build the Tour of Heroes.
+  and keeps the app running while you build the Tour of Heroes.
 
 .l-main-section
   :marked
-    ## Show our Hero
-    We want to display Hero data in our app
-
-    Let's add two properties to our `AppComponent`, a `title` property for the application name and a `hero` property
-    for a hero named "Windstorm".
+    ## Show Your Hero
+    To display Hero data in the app,
+    add two properties to the `AppComponent`: a `title` property for the application name and a `hero` property
+    <!-- Should we use "app" or "application", or if both, is there a distinction? -->
+    for a hero named "Windstorm."
 
   +makeExample('toh-1/ts-snippets/app.component.snippets.pt1.ts', 'app-component-1', 'app.component.ts (AppComponent class)')(format=".")
 
   :marked
-    Now we update the template in the `@Component` decoration with data bindings to these new properties.
+    Now update the template in the `@Component` decoration with data bindings to these new properties.
 
   +makeExample('toh-1/ts-snippets/app.component.snippets.pt1.ts', 'show-hero')
 
   :marked
-    The browser should refresh and display our title and hero.
+    The browser should refresh and display the title and hero name.
+    <!-- Do you prefer to present results directly or with "should"? I usually avoid the passive, but in this case
+         it could be justified. Either way, both styles are used in this chapter; can we choose one and be consistent? -->
 
-    The double curly braces tell our app to read the `title` and `hero` properties from the component and render them.
+    The double curly braces instruct the app to read the `title` and `hero` properties from the component and render them.
     This is the "interpolation" form of one-way data binding.
 .l-sub-section
   :marked
@@ -67,45 +67,46 @@ code-example(language="bash").
 :marked
   ### Hero object
 
-  At the moment, our hero is just a name.  Our hero needs more properties.
+  Our hero needs more properties.
   Let's convert the `hero` from a literal string to a class.
 
   Create a `Hero` class with `id` and `name` properties.
-  For now put this near the top of the `app.component.ts` file, just below the import statement.
+  For now, add these properties near the top of the `app.component.ts` file, just below the import statement.
 
 +makeExample('toh-1/ts/app/app.component.ts', 'hero-class-1', 'app.component.ts (Hero class)')(format=".")
 
 :marked
-  Now that we have a `Hero` class, let’s refactor our component’s `hero` property to be of type `Hero`.
-  Then initialize it with an id of `1` and the name, "Windstorm".
+  Now in your `Hero` class, refactor the component’s `hero` property to be of type `Hero`,
+  <!-- The Angular Team Writing Guidelines says to use straight quotes. Does that also apply to apostrophes? 
+       I see a lot of curly apostrophes in the content, though not consistently. --> 
+  then initialize it with an id of `1` and the name "Windstorm."
 
 +makeExample('toh-1/ts/app/app.component.ts', 'hero-property-1', 'app.component.ts (hero property)')(format=".")
 
 :marked
-  Because we changed the hero from a string to an object,
-  we update the binding in the template to refer to the hero’s `name` property.
+  Because you changed the hero from a string to an object,
+  update the binding in the template to refer to the hero’s `name` property.
 
 +makeExample('toh-1/ts-snippets/app.component.snippets.pt1.ts', 'show-hero-2')
 :marked
-  The browser refreshes and continues to display our hero’s name.
+  The browser refreshes and continues to display the hero’s name.
+  <!-- "should refresh..."? -->
 
   ### Adding more HTML
-  Displaying a name is good, but we want to see all of our hero’s properties.
-  We’ll add a `<div>` for our hero’s `id` property and another `<div>` for our hero’s `name`.
+  <!-- Can I remove this entire section and just explain the switch to multi-line strings in the next section? -->
+  Displaying a name is good, but we want to see all of the hero’s properties.
+  Add a `<div>` for the hero’s `id` property and another `<div>` for the hero’s `name`.
 
 +makeExample('toh-1/ts-snippets/app.component.snippets.pt1.ts', 'show-hero-properties')
 :marked
-  Uh oh, our template string is getting long. We better take care of that to avoid the risk of making a typo in the template.
+  Uh oh, the template string is getting long. Let's clean up the code to avoid making typos in the template.
 
   ### Multi-line template strings
 
-  We could make a more readable template with string concatenation
-  but that gets ugly fast, it is harder to read, and
-  it is easy to make a spelling error. Instead,
-  let’s take advantage of the template strings feature
-  in ES2015 and TypeScript to maintain our sanity.
+  Let’s use the template strings feature
+  in ES2015 and TypeScript.
 
-  Change the quotes around the template to back-ticks and
+  Change the quotes around the template to backticks and
   put the `<h1>`, `<h2>` and `<div>` elements on their own lines.
 
 +makeExample('toh-1/ts-snippets/app.component.snippets.pt1.ts', 'multi-line-strings', 'app.component.ts (AppComponent\'s template)')
@@ -119,33 +120,33 @@ code-example(language="bash").
       Here we use them in a limited way to spread the template over multiple lines.
       Everything between the back-ticks at the beginning and end of the template
       is part of a single template string.
+      <!-- I don't see this content in the browser. Is it supposed to appear? -->
 
 .l-main-section
 :marked
-  ## Editing Our Hero
+  ## Editing the Hero Name
 
   We want to be able to edit the hero name in a textbox.
 
-  Refactor the hero name `<label>` with `<label>` and `<input>` elements as shown below:
+  Refactor the hero name `<label>` with `<label>` and `<input>` elements as shown:
 
 +makeExample('toh-1/ts-snippets/app.component.snippets.pt1.ts', 'editing-Hero', 'app.component.ts (input element)')
 :marked
-  We see in the browser that the hero’s name does appear in the `<input>` textbox.
-  But something doesn’t feel right.
-  When we change the name, we notice that our change
-  is not reflected in the `<h2>`. We won't get the desired behavior
-  with a one-way binding to `<input>`.
+  The hero’s name now appears in the `<input>` textbox.
+  But if you change the name, you'll notice that your change
+  isn't reflected in the `<h2>`. To get the desired behavior,
+  you'll implement two-way binding to `<input>`.
 
   ### Two-Way Binding
 
   We intend to display the name of the hero in the `<input>`, change it,
   and see those changes wherever we bind to the hero’s name.
-  In short, we want two-way data binding.
+  This is known as two-way data binding.
 
-  Before we can use two-way data binding for **form inputs**, we need to import the `FormsModule`
-  package in our Angular module. We add it to the `NgModule` decorator's `imports` array. This array contains the list
-  of external modules used by our application.
-  Now we have included the forms package which includes `ngModel`.
+  Before using two-way data binding for **form inputs**, import the `FormsModule`
+  package in your Angular module. Add the `FormsModule` to the `NgModule` decorator's `imports` array, which contains the list
+  of external modules that the application uses.
+  Now you have included the forms package that includes `ngModel`.
 
 +makeExample('toh-1/ts/app/app.module.ts', '', 'app.module.ts (FormsModule import)')
 
@@ -156,30 +157,34 @@ code-example(language="bash").
     [Template Syntax](../guide/template-syntax.html#ngModel) chapters.
 
 :marked
-  Let’s update the template to use the  **`ngModel`** built-in directive for two-way binding.
+  Now update the template to use the  **`ngModel`** built-in directive for two-way binding.
 
-  Replace the `<input>` with the following HTML
+  Replace the `<input>` with the following HTML:
+  <!-- Would it be helpful to start this sentence with "In app.component.ts, replace ..." 
+       or will the proper file be obvious to the audience? -->
 
 code-example(language="html").
   &lt;input [(ngModel)]="hero.name" placeholder="name">
 
 :marked
-  The browser refreshes. We see our hero again. We can edit the hero’s name and
+  The browser refreshes. Now you can edit the hero’s name and
   see the changes reflected immediately in the `<h2>`.
 
 .l-main-section
 :marked
-  ## The Road We’ve Travelled
-  Let’s take stock of what we’ve built.
+  ## The Road You’ve Travelled
+  Let’s take stock of what you’ve built.
 
-  * Our Tour of Heroes uses the double curly braces of interpolation (a kind of one-way data binding)
+  * The Tour of Heroes app uses the double curly braces of interpolation (a type of one-way data binding)
   to display the application title and properties of a `Hero` object.
-  * We wrote a multi-line template using ES2015’s template strings to make our template readable.
-  * We can both display and change the hero’s name after adding a two-way data binding to the `<input>` element
-  using the built-in `ngModel` directive.
-  * The `ngModel` directive also propagates changes to every other binding of the `hero.name`.
+  * You wrote a multi-line template using ES2015’s template strings to make the template readable.
+  * You added a two-way data binding to the `<input>` element
+  using the built-in `ngModel` directive. This binding both displays the hero’s name and allows users to change it.
+  * The `ngModel` directive propagates changes to every other binding of the `hero.name`.
 
   Run the <live-example></live-example> for this part.
+  <!-- This seems unnecessary; users are instructed to run the live example at the beginning of the chapter,
+       and to refer to it throughout. -->
 
   Here's the complete `app.component.ts` as it stands now:
 
@@ -188,8 +193,10 @@ code-example(language="html").
 .l-main-section
 :marked
   ## The Road Ahead
-  Our Tour of Heroes only displays one hero and we really want to display a list of heroes.
-  We also want to allow the user to select a hero and display their details.
-  We’ll learn more about how to retrieve lists, bind them to the
+  In the next chapter, you'll build on the Tour of Heroes app to display a list of heroes.
+  You'll also allow the user to select heroes and display their details.
+  You’ll learn more about how to retrieve lists, bind them to the
   template, and allow a user to select a hero in the
   [next tutorial chapter](./toh-pt2.html).
+  <!-- There is an auto-generated link to the next chapter at the end of every chapter,   
+       so this link is redundant. Can I remove it? -->

From 4251e8cd37f92fb4cc72423a83892f287a38c1d4 Mon Sep 17 00:00:00 2001
From: Carol Franger <cfranger@gmail.com>
Date: Thu, 27 Oct 2016 12:39:17 -0700
Subject: [PATCH 2/5] WIP: testing push

---
 public/docs/ts/latest/tutorial/toh-pt1.jade | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/public/docs/ts/latest/tutorial/toh-pt1.jade b/public/docs/ts/latest/tutorial/toh-pt1.jade
index 01b08673a9..d5e2b5568a 100644
--- a/public/docs/ts/latest/tutorial/toh-pt1.jade
+++ b/public/docs/ts/latest/tutorial/toh-pt1.jade
@@ -30,7 +30,8 @@ include ../_quickstart_repo
     .file typings.json
 :marked
   ## Keep the app transpiling and running
-  Type the following command:
+  To start the TypeScript compiler, have it watch for changes, and start our server, type the following:
+  
 
 code-example(language="bash").
   npm start

From 7a6ad3b9cb850ec647a6417f8a5ef9d2aa05345d Mon Sep 17 00:00:00 2001
From: Carol Franger <cfranger@gmail.com>
Date: Thu, 27 Oct 2016 13:06:20 -0700
Subject: [PATCH 3/5] WIP: added "CF: " to my comments/questions

---
 public/docs/ts/latest/tutorial/toh-pt1.jade | 18 ++++++------------
 1 file changed, 6 insertions(+), 12 deletions(-)

diff --git a/public/docs/ts/latest/tutorial/toh-pt1.jade b/public/docs/ts/latest/tutorial/toh-pt1.jade
index d5e2b5568a..49104bfb81 100644
--- a/public/docs/ts/latest/tutorial/toh-pt1.jade
+++ b/public/docs/ts/latest/tutorial/toh-pt1.jade
@@ -45,7 +45,7 @@ code-example(language="bash").
     ## Show Your Hero
     To display Hero data in the app,
     add two properties to the `AppComponent`: a `title` property for the application name and a `hero` property
-    <!-- Should we use "app" or "application", or if both, is there a distinction? -->
+    <!-- CF: Should we use "app" or "application", or if both, is there a distinction? -->
     for a hero named "Windstorm."
 
   +makeExample('toh-1/ts-snippets/app.component.snippets.pt1.ts', 'app-component-1', 'app.component.ts (AppComponent class)')(format=".")
@@ -57,7 +57,7 @@ code-example(language="bash").
 
   :marked
     The browser should refresh and display the title and hero name.
-    <!-- Do you prefer to present results directly or with "should"? I usually avoid the passive, but in this case
+    <!-- CF: Do you prefer to present results directly or with "should"? I usually avoid the passive, but in this case
          it could be justified. Either way, both styles are used in this chapter; can we choose one and be consistent? -->
 
     The double curly braces instruct the app to read the `title` and `hero` properties from the component and render them.
@@ -78,8 +78,6 @@ code-example(language="bash").
 
 :marked
   Now in your `Hero` class, refactor the component’s `hero` property to be of type `Hero`,
-  <!-- The Angular Team Writing Guidelines says to use straight quotes. Does that also apply to apostrophes? 
-       I see a lot of curly apostrophes in the content, though not consistently. --> 
   then initialize it with an id of `1` and the name "Windstorm."
 
 +makeExample('toh-1/ts/app/app.component.ts', 'hero-property-1', 'app.component.ts (hero property)')(format=".")
@@ -91,10 +89,10 @@ code-example(language="bash").
 +makeExample('toh-1/ts-snippets/app.component.snippets.pt1.ts', 'show-hero-2')
 :marked
   The browser refreshes and continues to display the hero’s name.
-  <!-- "should refresh..."? -->
+  <!-- CF: "should refresh..."? -->
 
   ### Adding more HTML
-  <!-- Can I remove this entire section and just explain the switch to multi-line strings in the next section? -->
+  <!-- CF: Can I remove this entire section and just explain the switch to multi-line strings in the next section? -->
   Displaying a name is good, but we want to see all of the hero’s properties.
   Add a `<div>` for the hero’s `id` property and another `<div>` for the hero’s `name`.
 
@@ -121,7 +119,7 @@ code-example(language="bash").
       Here we use them in a limited way to spread the template over multiple lines.
       Everything between the back-ticks at the beginning and end of the template
       is part of a single template string.
-      <!-- I don't see this content in the browser. Is it supposed to appear? -->
+      <!-- CF: I don't see this content in the browser. Is it supposed to appear? -->
 
 .l-main-section
 :marked
@@ -161,7 +159,7 @@ code-example(language="bash").
   Now update the template to use the  **`ngModel`** built-in directive for two-way binding.
 
   Replace the `<input>` with the following HTML:
-  <!-- Would it be helpful to start this sentence with "In app.component.ts, replace ..." 
+  <!-- CF: Would it be helpful to start this sentence with "In app.component.ts, replace ..." 
        or will the proper file be obvious to the audience? -->
 
 code-example(language="html").
@@ -184,8 +182,6 @@ code-example(language="html").
   * The `ngModel` directive propagates changes to every other binding of the `hero.name`.
 
   Run the <live-example></live-example> for this part.
-  <!-- This seems unnecessary; users are instructed to run the live example at the beginning of the chapter,
-       and to refer to it throughout. -->
 
   Here's the complete `app.component.ts` as it stands now:
 
@@ -199,5 +195,3 @@ code-example(language="html").
   You’ll learn more about how to retrieve lists, bind them to the
   template, and allow a user to select a hero in the
   [next tutorial chapter](./toh-pt2.html).
-  <!-- There is an auto-generated link to the next chapter at the end of every chapter,   
-       so this link is redundant. Can I remove it? -->

From da4e27d357e5cd4f837cb666b2d9bc979f7ce527 Mon Sep 17 00:00:00 2001
From: Carol Franger <cfranger@gmail.com>
Date: Thu, 27 Oct 2016 18:16:09 -0700
Subject: [PATCH 4/5] WIP: 10/27 updates

---
 public/docs/ts/latest/tutorial/toh-pt1.jade | 84 ++++++++-----------
 public/docs/ts/latest/tutorial/toh-pt2.jade | 93 +++++++++++----------
 2 files changed, 85 insertions(+), 92 deletions(-)

diff --git a/public/docs/ts/latest/tutorial/toh-pt1.jade b/public/docs/ts/latest/tutorial/toh-pt1.jade
index 49104bfb81..78f2489710 100644
--- a/public/docs/ts/latest/tutorial/toh-pt1.jade
+++ b/public/docs/ts/latest/tutorial/toh-pt1.jade
@@ -2,8 +2,11 @@ include ../_util-fns
 
 :marked
   # Once Upon a Time
+  
+  Every story starts somewhere. 
+  Our story starts where the [QuickStart](../quickstart.html) ends.
 
-  Run the <live-example></live-example>.
+  **Try it out**. Here's a link to a <live-example></live-example>.
 
   Create a folder called `angular-tour-of-heroes` and follow the [QuickStart](../quickstart.html) steps,
   which provide the prerequisites, folder structure, and core files for the Tour of Heroes.
@@ -30,22 +33,21 @@ include ../_quickstart_repo
     .file typings.json
 :marked
   ## Keep the app transpiling and running
-  To start the TypeScript compiler, have it watch for changes, and start our server, type the following:
+  To start the TypeScript compiler in watch mode and start the server, type the following:
   
 
 code-example(language="bash").
   npm start
 
 :marked
-  This command runs the compiler in watch mode, starts the server, launches the app in a browser,
+  This command launches the app in a browser
   and keeps the app running while you build the Tour of Heroes.
 
 .l-main-section
   :marked
     ## Show Your Hero
     To display Hero data in the app,
-    add two properties to the `AppComponent`: a `title` property for the application name and a `hero` property
-    <!-- CF: Should we use "app" or "application", or if both, is there a distinction? -->
+    add two properties to the `AppComponent`: a `title` property for the app name and a `hero` property
     for a hero named "Windstorm."
 
   +makeExample('toh-1/ts-snippets/app.component.snippets.pt1.ts', 'app-component-1', 'app.component.ts (AppComponent class)')(format=".")
@@ -56,9 +58,7 @@ code-example(language="bash").
   +makeExample('toh-1/ts-snippets/app.component.snippets.pt1.ts', 'show-hero')
 
   :marked
-    The browser should refresh and display the title and hero name.
-    <!-- CF: Do you prefer to present results directly or with "should"? I usually avoid the passive, but in this case
-         it could be justified. Either way, both styles are used in this chapter; can we choose one and be consistent? -->
+    The browser refreshes and display the title and hero name.
 
     The double curly braces instruct the app to read the `title` and `hero` properties from the component and render them.
     This is the "interpolation" form of one-way data binding.
@@ -72,41 +72,32 @@ code-example(language="bash").
   Let's convert the `hero` from a literal string to a class.
 
   Create a `Hero` class with `id` and `name` properties.
-  For now, add these properties near the top of the `app.component.ts` file, just below the import statement.
+  Add these properties near the top of the `app.component.ts` file, just below the import statement.
 
 +makeExample('toh-1/ts/app/app.component.ts', 'hero-class-1', 'app.component.ts (Hero class)')(format=".")
 
 :marked
-  Now in your `Hero` class, refactor the component’s `hero` property to be of type `Hero`,
+  Now in your `Hero` class, refactor the component's `hero` property to be of type `Hero`,
   then initialize it with an id of `1` and the name "Windstorm."
 
 +makeExample('toh-1/ts/app/app.component.ts', 'hero-property-1', 'app.component.ts (hero property)')(format=".")
 
 :marked
   Because you changed the hero from a string to an object,
-  update the binding in the template to refer to the hero’s `name` property.
+  update the binding in the template to refer to the hero's `name` property.
 
 +makeExample('toh-1/ts-snippets/app.component.snippets.pt1.ts', 'show-hero-2')
 :marked
-  The browser refreshes and continues to display the hero’s name.
-  <!-- CF: "should refresh..."? -->
-
-  ### Adding more HTML
-  <!-- CF: Can I remove this entire section and just explain the switch to multi-line strings in the next section? -->
-  Displaying a name is good, but we want to see all of the hero’s properties.
-  Add a `<div>` for the hero’s `id` property and another `<div>` for the hero’s `name`.
-
-+makeExample('toh-1/ts-snippets/app.component.snippets.pt1.ts', 'show-hero-properties')
-:marked
-  Uh oh, the template string is getting long. Let's clean up the code to avoid making typos in the template.
+  The browser refreshes and continues to display the hero's name.
 
-  ### Multi-line template strings
+  ### Adding HTML with multi-line template strings
 
-  Let’s use the template strings feature
-  in ES2015 and TypeScript.
-
-  Change the quotes around the template to backticks and
-  put the `<h1>`, `<h2>` and `<div>` elements on their own lines.
+  Displaying a name is good, but we want to see all of the hero's properties.
+  For this update, you'll add a `<div>` for the hero's `id` property and another `<div>` for the hero's `name`.
+  To keep the template readable, you'll make some additional changes using the template strings feature
+  in ES2015 and TypeScript:
+  change the quotes around the template to backticks
+  and put the `<h1>`, `<h2>`, and `<div>` elements on their own lines.
 
 +makeExample('toh-1/ts-snippets/app.component.snippets.pt1.ts', 'multi-line-strings', 'app.component.ts (AppComponent\'s template)')
 
@@ -119,7 +110,8 @@ code-example(language="bash").
       Here we use them in a limited way to spread the template over multiple lines.
       Everything between the back-ticks at the beginning and end of the template
       is part of a single template string.
-      <!-- CF: I don't see this content in the browser. Is it supposed to appear? -->
+      <!-- CF: I don't see this content in the browser. I asked Naomi and she doesn't
+       think this content is necessary. If we decide to keep it, I'll do an edit pass. -->
 
 .l-main-section
 :marked
@@ -131,7 +123,7 @@ code-example(language="bash").
 
 +makeExample('toh-1/ts-snippets/app.component.snippets.pt1.ts', 'editing-Hero', 'app.component.ts (input element)')
 :marked
-  The hero’s name now appears in the `<input>` textbox.
+  The hero's name now appears in the `<input>` textbox.
   But if you change the name, you'll notice that your change
   isn't reflected in the `<h2>`. To get the desired behavior,
   you'll implement two-way binding to `<input>`.
@@ -139,12 +131,12 @@ code-example(language="bash").
   ### Two-Way Binding
 
   We intend to display the name of the hero in the `<input>`, change it,
-  and see those changes wherever we bind to the hero’s name.
+  and see those changes wherever we bind to the hero's name.
   This is known as two-way data binding.
 
   Before using two-way data binding for **form inputs**, import the `FormsModule`
   package in your Angular module. Add the `FormsModule` to the `NgModule` decorator's `imports` array, which contains the list
-  of external modules that the application uses.
+  of external modules that the app uses.
   Now you have included the forms package that includes `ngModel`.
 
 +makeExample('toh-1/ts/app/app.module.ts', '', 'app.module.ts (FormsModule import)')
@@ -157,32 +149,29 @@ code-example(language="bash").
 
 :marked
   Now update the template to use the  **`ngModel`** built-in directive for two-way binding.
-
-  Replace the `<input>` with the following HTML:
-  <!-- CF: Would it be helpful to start this sentence with "In app.component.ts, replace ..." 
-       or will the proper file be obvious to the audience? -->
+  In app.component.ts, replace the `<input>` with the following HTML:
 
 code-example(language="html").
   &lt;input [(ngModel)]="hero.name" placeholder="name">
 
 :marked
-  The browser refreshes. Now you can edit the hero’s name and
+  The browser refreshes. Now you can edit the hero's name and
   see the changes reflected immediately in the `<h2>`.
 
 .l-main-section
 :marked
-  ## The Road You’ve Travelled
-  Let’s take stock of what you’ve built.
+  ## The Road You've Travelled
+  Let's take stock of what you've built.
 
   * The Tour of Heroes app uses the double curly braces of interpolation (a type of one-way data binding)
-  to display the application title and properties of a `Hero` object.
-  * You wrote a multi-line template using ES2015’s template strings to make the template readable.
+  to display the app title and properties of a `Hero` object.
+  * You wrote a multi-line template using ES2015's template strings to make the template readable.
   * You added a two-way data binding to the `<input>` element
-  using the built-in `ngModel` directive. This binding both displays the hero’s name and allows users to change it.
+  using the built-in `ngModel` directive. This binding both displays the hero's name and allows users to change it.
   * The `ngModel` directive propagates changes to every other binding of the `hero.name`.
 
-  Run the <live-example></live-example> for this part.
-
+  **Try it out**. Here's a link to a <live-example></live-example>.
+ 
   Here's the complete `app.component.ts` as it stands now:
 
 +makeExample('toh-1/ts/app/app.component.ts', 'pt1', 'app.component.ts')
@@ -190,8 +179,7 @@ code-example(language="html").
 .l-main-section
 :marked
   ## The Road Ahead
-  In the next chapter, you'll build on the Tour of Heroes app to display a list of heroes.
+  In the [next tutorial chapter](./toh-pt2.html), you'll build on the Tour of Heroes app to display a list of heroes.
   You'll also allow the user to select heroes and display their details.
-  You’ll learn more about how to retrieve lists, bind them to the
-  template, and allow a user to select a hero in the
-  [next tutorial chapter](./toh-pt2.html).
+  You'll learn more about how to retrieve lists, bind them to the
+  template, and allow a user to select a hero.
diff --git a/public/docs/ts/latest/tutorial/toh-pt2.jade b/public/docs/ts/latest/tutorial/toh-pt2.jade
index fbf3d6325f..2c6fed6f60 100644
--- a/public/docs/ts/latest/tutorial/toh-pt2.jade
+++ b/public/docs/ts/latest/tutorial/toh-pt2.jade
@@ -3,21 +3,23 @@ include ../_util-fns
 :marked
   # It Takes Many Heroes
   Our story needs more heroes.
-  We’ll expand our Tour of Heroes app to display a list of heroes,
-  allow the user to select a hero, and display the hero’s details.
+  In this chapter, you'll expand the Tour of Heroes app to display a list of heroes,
+  allow the user to select a hero, and display the hero's details.
 
-  Run the <live-example></live-example> for this part.
+  **Try it out**. Here's a link to a <live-example></live-example>.
 
-  Let’s take stock of what we’ll need to display a list of heroes.
-  First, we need a list of heroes. We want to display those heroes in the view’s template,
-  so we’ll need a way to do that.
+  To display a list of heroes,
+  you need to add the heroes to the view's template.
+//  CF: I edited this paragraph down to its core, but am not sure it's necessary or relevant here.
+  
 
 .l-main-section
 :marked
-  ## Where We Left Off
-  Before we continue with Part 2 of the Tour of Heroes,
-  let’s verify we have the following structure after [Part 1](./toh-pt1.html).
-  If not, we’ll need to go back to Part 1 and figure out what we missed.
+  ## Where You Left Off
+  Before you continue with Part 2 of the Tour of Heroes,
+  verify that you have the following structure after [Part 1](./toh-pt1.html).
+  If not, you'll need to go back to Part 1 and figure out what you missed.
+// CF: "Part 1" and "part 2" might be confusing to readers, as they are numbered 2 and 3 in the left nav bar.
 
 .filetree
   .file angular-tour-of-heroes
@@ -36,46 +38,46 @@ include ../_util-fns
     .file tsconfig.json
     .file typings.json
 :marked
-  ### Keep the app transpiling and running
-  We want to start the TypeScript compiler, have it watch for changes, and start our server. We'll do this by typing
+  ## Keep the app transpiling and running
+  To start the TypeScript compiler in watch mode and start the server, type the following:
 
 code-example(language="bash").
   npm start
 
 :marked
-  This will keep the application running while we continue to build the Tour of Heroes.
+  This command keeps the application running while you continue to build the Tour of Heroes.
 
 .l-main-section
 :marked
   ## Displaying Our Heroes
   ### Creating heroes
-  Let’s create an array of ten heroes.
+  Create an array of ten heroes.
 
 +makeExample('toh-2/ts/app/app.component.ts', 'hero-array', 'app.component.ts (hero array)')
 
 :marked
-  The `HEROES` array is of type `Hero`, the class defined in part one, 
+  The `HEROES` array is of type `Hero`, the class defined in part 1, 
   to create an array of heroes.
-  We aspire to fetch this list of heroes from a web service, but let’s take small steps
+  We aspire to fetch this list of heroes from a web service, but you'll take small steps
   first and display mock heroes.
 
   ### Exposing heroes
-  Let’s create a public property in `AppComponent` that exposes the heroes for binding.
+  Create a public property in `AppComponent` that exposes the heroes for binding.
 
 +makeExample('toh-2/ts-snippets/app.component.snippets.pt2.ts', 'hero-array-1', 'app.component.ts (hero array property)')
 
 :marked
-  We did not have to define the `heroes` type.  TypeScript can infer it from the `HEROES` array.
+  You didn't have to define the `heroes` type.  TypeScript can infer it from the `HEROES` array.
 .l-sub-section
   :marked
     We could have defined the heroes list here in this component class.
-    But we know that ultimately we’ll get the heroes from a data service.
+    But we know that ultimately we'll get the heroes from a data service.
     Because we know where we are heading, it makes sense to separate the hero data
     from the class implementation from the start.
 :marked
   ### Displaying heroes in a template
-  Our component has `heroes`. Let’s create an unordered list in our template to display them.
-  We’ll insert the following chunk of HTML below the title and above the hero details.
+  Our component has `heroes`. Let's create an unordered list in our template to display them.
+  We'll insert the following chunk of HTML below the title and above the hero details.
 
 +makeExample('toh-2/ts-snippets/app.component.snippets.pt2.ts', 'heroes-template-1', 'app.component.ts (heroes template)')
 
@@ -86,7 +88,7 @@ code-example(language="bash").
 
   We want to bind the array of `heroes` in our component to our template, iterate over them,
   and display them individually.
-  We’ll need some help from Angular to do this. Let’s do this step by step.
+  We'll need some help from Angular to do this. Let's do this step by step.
 
   First modify the `<li>` tag by adding the built-in directive `*ngFor`.
 
@@ -109,7 +111,7 @@ code-example(language="bash").
     and make it available to the corresponding template instance*”.
 
     The `let` keyword before "hero" identifies `hero` as a template input variable.
-    We can reference this variable within the template to access a hero’s properties.
+    We can reference this variable within the template to access a hero's properties.
 
     Learn more about `ngFor` and template input variables in the
     [Displaying Data](../guide/displaying-data.html#ngFor) and
@@ -117,7 +119,7 @@ code-example(language="bash").
 
 :marked
   Now we insert some content between the `<li>` tags
-  that uses the `hero` template variable to display the hero’s properties.
+  that uses the `hero` template variable to display the hero's properties.
 
 +makeExample('toh-2/ts-snippets/app.component.snippets.pt2.ts', 'ng-for', 'app.component.ts (ngFor template)')(format=".")
 
@@ -128,7 +130,7 @@ code-example(language="bash").
   Our list of heroes looks pretty bland.
   We want to make it visually obvious to a user which hero we are hovering over and which hero is selected.
 
-  Let’s add some styles to our component by setting the `styles` property on the `@Component` decorator
+  Let's add some styles to our component by setting the `styles` property on the `@Component` decorator
   to the following CSS classes:
 
 +makeExample('toh-2/ts/app/app.component.ts', 'styles', 'app.component.ts (styles)')(format=".")
@@ -155,7 +157,7 @@ code-example(language="bash").
     This UI pattern is widely known as "master-detail".
     In our case, the master is the heroes list and the detail is the selected hero.
 
-    Let’s connect the master to the detail through a `selectedHero` component property bound to a click event.
+    Let's connect the master to the detail through a `selectedHero` component property bound to a click event.
 
     ### Click event
     We modify the `<li>` by inserting an Angular event binding to its click event.
@@ -167,10 +169,10 @@ code-example(language="bash").
   code-example(format="." language="bash").
     (click)="onSelect(hero)"
   :marked
-    The parenthesis identify the `<li>` element’s  `click` event as the target.
+    The parenthesis identify the `<li>` element's  `click` event as the target.
     The expression to the right of the equal sign calls the  `AppComponent` method, `onSelect()`,
     passing the template input variable `hero` as an argument.
-    That’s the same `hero` variable we defined previously in the `ngFor`.
+    That's the same `hero` variable we defined previously in the `ngFor`.
   .l-sub-section
     :marked
       Learn more about Event Binding in the 
@@ -178,12 +180,12 @@ code-example(language="bash").
       [Templating Syntax](../guide/template-syntax.html#event-binding) chapters.
   :marked
     ### Add the click handler
-    Our event binding refers to an `onSelect` method that doesn’t exist yet.
-    We’ll add that method to our component now.
+    Our event binding refers to an `onSelect` method that doesn't exist yet.
+    We'll add that method to our component now.
 
-    What should that method do? It should set the component’s selected hero to the hero that the user clicked.
+    What should that method do? It should set the component's selected hero to the hero that the user clicked.
 
-    Our component doesn’t have a “selected hero” yet either. We’ll start there.
+    Our component doesn't have a “selected hero” yet either. We'll start there.
 
     ### Expose the selected hero
 
@@ -193,8 +195,8 @@ code-example(language="bash").
   +makeExample('toh-2/ts/app/app.component.ts', 'selected-hero', 'app.component.ts (selectedHero)')
 
   :marked
-    We’ve decided that none of the heroes should be selected before the user picks a hero so
-    we won’t initialize the `selectedHero` as we were doing with `hero`.
+    We've decided that none of the heroes should be selected before the user picks a hero so
+    we won't initialize the `selectedHero` as we were doing with `hero`.
 
     Now **add an `onSelect` method** that sets the `selectedHero` property to the `hero` the user clicked.
   +makeExample('toh-2/ts/app/app.component.ts', 'on-select', 'app.component.ts (onSelect)')
@@ -202,7 +204,7 @@ code-example(language="bash").
   :marked
     We will be showing the selected hero's details in our template.
     At the moment, it is still referring to the old `hero` property.
-    Let’s fix the template to bind to the new `selectedHero` property.
+    Let's fix the template to bind to the new `selectedHero` property.
 
   +makeExample('toh-2/ts-snippets/app.component.snippets.pt2.ts', 'selectedHero-details', 'app.component.ts (template excerpt)')
   :marked
@@ -210,7 +212,7 @@ code-example(language="bash").
 
     When our app loads we see a list of heroes, but a hero is not selected.
     The `selectedHero` is `undefined`.
-    That’s why we'll see the following error in the browser’s console:
+    That's why we'll see the following error in the browser's console:
 
   code-example(language="html").
     EXCEPTION: TypeError: Cannot read property 'name' of undefined in [null]
@@ -254,18 +256,20 @@ code-example(language="bash").
 
     ### Styling the selection
 
-    We see the selected hero in the details area below but we can’t quickly locate that hero in the list above.
+    We see the selected hero in the details area below but we can't quickly locate that hero in the list above.
     We can fix that by applying the `selected` CSS class to the appropriate `<li>` in the master list.
     For example, when we select Magneta from the heroes list,
     we can make it pop out visually by giving it a subtle background color as shown here.
+  //  CF: At this point I already see the background color on the selected hero. 
+    Also, the font in the screen shot doesn't match the sans serif font in my browser (maybe not a big deal).
 
   figure.image-display
     img(src='/resources/images/devguide/toh/heroes-list-selected.png' alt="Selected hero")
   :marked
-    We’ll add a property binding on `class` for the `selected` class to the template. We'll set this to an expression that compares the current `selectedHero` to the `hero`.
+    We'll add a property binding on `class` for the `selected` class to the template. We'll set this to an expression that compares the current `selectedHero` to the `hero`.
 
     The key is the name of the CSS class (`selected`). The value is `true` if the two heroes match and `false` otherwise.
-    We’re saying “*apply the `selected` class if the heroes match, remove it if they don’t*”.
+    We're saying “*apply the `selected` class if the heroes match, remove it if they don't*”.
   +makeExample('toh-2/ts-snippets/app.component.snippets.pt2.ts', 'class-selected-1', 'app.component.ts (setting the CSS class)')(format=".")
   :marked
     Notice in the template that the `class.selected` is surrounded in square brackets (`[]`).
@@ -284,6 +288,7 @@ code-example(language="bash").
 
   figure.image-display
     img(src='/resources/images/devguide/toh/heroes-list-1.png' alt="Output of heroes list app")
+  //  CF: The font in the screen shot doesn't match the sans serif font in my browser output.
 
   :marked
     We select a different hero and the tell-tale color switches to that hero.
@@ -294,17 +299,17 @@ code-example(language="bash").
 
 .l-main-section
 :marked
-  ## The Road We’ve Travelled
-  Here’s what we achieved in this chapter:
+  ## The Road We've Travelled
+  Here's what we achieved in this chapter:
 
   * Our Tour of Heroes now displays a list of selectable heroes
-  * We added the ability to select a hero and show the hero’s details
-  * We learned how to use the built-in directives `ngIf` and `ngFor` in a component’s template
+  * We added the ability to select a hero and show the hero's details
+  * We learned how to use the built-in directives `ngIf` and `ngFor` in a component's template
 
   Run the <live-example></live-example> for this part.
 
   ### The Road Ahead
-  Our Tour of Heroes has grown, but it’s far from complete.
+  Our Tour of Heroes has grown, but it's far from complete.
   We can't put the entire app into a single component.
   We need to break it up into sub-components and teach them to work together
   as we learn in the [next chapter](toh-pt3.html).

From c546dac37470d0f4869eee7beb373370decc684c Mon Sep 17 00:00:00 2001
From: Carol Franger <cfranger@gmail.com>
Date: Fri, 28 Oct 2016 17:33:39 -0700
Subject: [PATCH 5/5] WIP: full edit pass on these pages, as well as some
 questions. Please see my comments starting with "CF:"

---
 public/docs/ts/latest/tutorial/toh-pt1.jade |  30 +--
 public/docs/ts/latest/tutorial/toh-pt2.jade | 220 ++++++++++----------
 2 files changed, 124 insertions(+), 126 deletions(-)

diff --git a/public/docs/ts/latest/tutorial/toh-pt1.jade b/public/docs/ts/latest/tutorial/toh-pt1.jade
index 78f2489710..c3e95ce6d0 100644
--- a/public/docs/ts/latest/tutorial/toh-pt1.jade
+++ b/public/docs/ts/latest/tutorial/toh-pt1.jade
@@ -45,8 +45,8 @@ code-example(language="bash").
 
 .l-main-section
   :marked
-    ## Show Your Hero
-    To display Hero data in the app,
+    ## Show your hero
+    To display hero data in the app,
     add two properties to the `AppComponent`: a `title` property for the app name and a `hero` property
     for a hero named "Windstorm."
 
@@ -64,7 +64,7 @@ code-example(language="bash").
     This is the "interpolation" form of one-way data binding.
 .l-sub-section
   :marked
-    Learn more about interpolation in the [Displaying Data chapter](../guide/displaying-data.html).
+    Learn more about interpolation in the [Displaying Data page](../guide/displaying-data.html).
 :marked
   ### Hero object
 
@@ -101,21 +101,11 @@ code-example(language="bash").
 
 +makeExample('toh-1/ts-snippets/app.component.snippets.pt1.ts', 'multi-line-strings', 'app.component.ts (AppComponent\'s template)')
 
-  .callout.is-important
-    header A back-tick is not a single quote
-    :marked
-      **Be careful!** A back-tick (`) looks a lot like a single quote (').
-      It's actually a completely different character.
-      Back-ticks can do more than demarcate a string.
-      Here we use them in a limited way to spread the template over multiple lines.
-      Everything between the back-ticks at the beginning and end of the template
-      is part of a single template string.
-      <!-- CF: I don't see this content in the browser. I asked Naomi and she doesn't
-       think this content is necessary. If we decide to keep it, I'll do an edit pass. -->
+// CF: I removed the note about backticks. It wasn't appearing in the browser and Naomi didn't think it was necessary.
 
 .l-main-section
 :marked
-  ## Editing the Hero Name
+  ## Editing the hero name
 
   We want to be able to edit the hero name in a textbox.
 
@@ -128,7 +118,7 @@ code-example(language="bash").
   isn't reflected in the `<h2>`. To get the desired behavior,
   you'll implement two-way binding to `<input>`.
 
-  ### Two-Way Binding
+  ### Two-way binding
 
   We intend to display the name of the hero in the `<input>`, change it,
   and see those changes wherever we bind to the hero's name.
@@ -145,7 +135,7 @@ code-example(language="bash").
   :marked
     Learn more about the `FormsModule` and `ngModel` in the
     [Forms](../guide/forms.html#ngModel) and
-    [Template Syntax](../guide/template-syntax.html#ngModel) chapters.
+    [Template Syntax](../guide/template-syntax.html#ngModel) pages.
 
 :marked
   Now update the template to use the  **`ngModel`** built-in directive for two-way binding.
@@ -160,7 +150,7 @@ code-example(language="html").
 
 .l-main-section
 :marked
-  ## The Road You've Travelled
+  ## The road you've travelled
   Let's take stock of what you've built.
 
   * The Tour of Heroes app uses the double curly braces of interpolation (a type of one-way data binding)
@@ -178,8 +168,8 @@ code-example(language="html").
 
 .l-main-section
 :marked
-  ## The Road Ahead
-  In the [next tutorial chapter](./toh-pt2.html), you'll build on the Tour of Heroes app to display a list of heroes.
+  ## The road ahead
+  In the [next tutorial page](./toh-pt2.html), you'll build on the Tour of Heroes app to display a list of heroes.
   You'll also allow the user to select heroes and display their details.
   You'll learn more about how to retrieve lists, bind them to the
   template, and allow a user to select a hero.
diff --git a/public/docs/ts/latest/tutorial/toh-pt2.jade b/public/docs/ts/latest/tutorial/toh-pt2.jade
index 2c6fed6f60..4d71a1bee9 100644
--- a/public/docs/ts/latest/tutorial/toh-pt2.jade
+++ b/public/docs/ts/latest/tutorial/toh-pt2.jade
@@ -3,23 +3,20 @@ include ../_util-fns
 :marked
   # It Takes Many Heroes
   Our story needs more heroes.
-  In this chapter, you'll expand the Tour of Heroes app to display a list of heroes,
+  In this page, you'll expand the Tour of Heroes app to display a list of heroes,
   allow the user to select a hero, and display the hero's details.
 
   **Try it out**. Here's a link to a <live-example></live-example>.
-
-  To display a list of heroes,
-  you need to add the heroes to the view's template.
-//  CF: I edited this paragraph down to its core, but am not sure it's necessary or relevant here.
   
-
+  
 .l-main-section
 :marked
-  ## Where You Left Off
+  ## Where you left off
   Before you continue with Part 2 of the Tour of Heroes,
   verify that you have the following structure after [Part 1](./toh-pt1.html).
   If not, you'll need to go back to Part 1 and figure out what you missed.
-// CF: "Part 1" and "part 2" might be confusing to readers, as they are numbered 2 and 3 in the left nav bar.
+// CF: In the left nav bar, "Part 1" is numbered "2" and "Part 2" is numbered "3,"
+ so referring to "Part 1" etc. could be confusing.
 
 .filetree
   .file angular-tour-of-heroes
@@ -49,17 +46,21 @@ code-example(language="bash").
 
 .l-main-section
 :marked
-  ## Displaying Our Heroes
+  ## Displaying heroes
+  To display a list of heroes, you'll add the heroes to the view's template.
+  
   ### Creating heroes
   Create an array of ten heroes.
+//  CF: I don't see a rule in the Angular Writing Guidelines for task titles. Is there a 
+  preference for using gerunds ("Creating heroes") or imperatives ("Create heroes")?
+  Both styles are used in this tutorial.
 
 +makeExample('toh-2/ts/app/app.component.ts', 'hero-array', 'app.component.ts (hero array)')
 
 :marked
-  The `HEROES` array is of type `Hero`, the class defined in part 1, 
-  to create an array of heroes.
-  We aspire to fetch this list of heroes from a web service, but you'll take small steps
-  first and display mock heroes.
+  The `HEROES` array is of type `Hero`, the class defined in the previous page.
+  We aspire to fetch the list of heroes from a web service, but you'll take small steps
+  and display mock heroes for now.
 
   ### Exposing heroes
   Create a public property in `AppComponent` that exposes the heroes for binding.
@@ -67,36 +68,38 @@ code-example(language="bash").
 +makeExample('toh-2/ts-snippets/app.component.snippets.pt2.ts', 'hero-array-1', 'app.component.ts (hero array property)')
 
 :marked
-  You didn't have to define the `heroes` type.  TypeScript can infer it from the `HEROES` array.
+  You didn't have to define the `heroes` type because TypeScript infers it from the `HEROES` array.
 .l-sub-section
   :marked
-    We could have defined the heroes list here in this component class.
-    But we know that ultimately we'll get the heroes from a data service.
-    Because we know where we are heading, it makes sense to separate the hero data
+    You could define the heroes list in the component class,
+    but ultimately you'll get the heroes from a data service.
+    Because we know where we're heading, it makes sense to separate the hero data
     from the class implementation from the start.
 :marked
   ### Displaying heroes in a template
-  Our component has `heroes`. Let's create an unordered list in our template to display them.
-  We'll insert the following chunk of HTML below the title and above the hero details.
+  Your component has `heroes`. To display the hero names in an unordered list,
+  insert the following chunk of HTML below the title and above the hero details.
 
 +makeExample('toh-2/ts-snippets/app.component.snippets.pt2.ts', 'heroes-template-1', 'app.component.ts (heroes template)')
 
 :marked
-  Now we have a template that we can fill with our heroes.
+  Now you can fill the template with hero names.
 
   ### Listing heroes with ngFor
 
-  We want to bind the array of `heroes` in our component to our template, iterate over them,
+  Next, you'll bind the array of `heroes` in your component to your template, iterate over them,
   and display them individually.
-  We'll need some help from Angular to do this. Let's do this step by step.
+  You'll need some help from Angular to do this.
 
-  First modify the `<li>` tag by adding the built-in directive `*ngFor`.
+  First, modify the `<li>` tag by adding the built-in directive `*ngFor`.
 
 +makeExample('toh-2/ts-snippets/app.component.snippets.pt2.ts', 'heroes-ngfor-1', 'app.component.ts (ngFor)')
 
 .alert.is-critical
   :marked
     The leading asterisk (`*`) in front of `ngFor` is a critical part of this syntax.
+//  CF: is a "critical" type note appropriate here? Could we merge this sentence with
+    the .l-sub-section below?
 
 .l-sub-section
   :marked
@@ -107,191 +110,196 @@ code-example(language="bash").
     and stamps out instances of this template.
 
     The quoted text assigned to `ngFor` means
-    “*take each hero in the `heroes` array, store it in the local `hero` variable,
-    and make it available to the corresponding template instance*”.
+    “*in the `heroes` array, store each hero in the local `hero` variable
+    and make it available to the corresponding template instance*.”
 
     The `let` keyword before "hero" identifies `hero` as a template input variable.
     We can reference this variable within the template to access a hero's properties.
 
     Learn more about `ngFor` and template input variables in the
     [Displaying Data](../guide/displaying-data.html#ngFor) and
-    [Template Syntax](../guide/template-syntax.html#ngFor) chapters.
+    [Template Syntax](../guide/template-syntax.html#ngFor) pages.
 
 :marked
-  Now we insert some content between the `<li>` tags
+  Next, update the `<li>` tags to add content
   that uses the `hero` template variable to display the hero's properties.
 
 +makeExample('toh-2/ts-snippets/app.component.snippets.pt2.ts', 'ng-for', 'app.component.ts (ngFor template)')(format=".")
 
 :marked
-  When the browser refreshes, we see a list of heroes!
+  When the browser refreshes, you see a list of heroes.
 
   ### Styling our heroes
-  Our list of heroes looks pretty bland.
-  We want to make it visually obvious to a user which hero we are hovering over and which hero is selected.
+  The list of heroes looks pretty bland.
+  We want to give users a visual cue of which hero they are hovering over and which hero is selected.
 
-  Let's add some styles to our component by setting the `styles` property on the `@Component` decorator
+  To add some styles to your component, set the `styles` property on the `@Component` decorator
   to the following CSS classes:
 
 +makeExample('toh-2/ts/app/app.component.ts', 'styles', 'app.component.ts (styles)')(format=".")
 
 :marked
-  Notice that we again use the back-tick notation for multi-line strings.
+  Notice that again you use the backtick notation for multi-line strings.
 
-  That's a lot of styles! We can put them inline as shown here, or we can move them out to their own file which will make it easier to code our component. 
-  We'll do this in a later chapter. For now let's keep rolling.
+  That's a lot of styles! In a later page, you'll move the styles to a separate file. 
 
-  When we assign styles to a component they are scoped to that specific component.
-  Our styles will only apply to our `AppComponent` and won't "leak" to the outer HTML.
+  When you assign styles to a component, they are scoped to that specific component.
+  These styles apply only to your `AppComponent` and won't affect the outer HTML.
 
-  Our template for displaying the heroes should now look like this:
+  Your template for displaying the heroes should look like this:
 
 +makeExample('toh-2/ts-snippets/app.component.snippets.pt2.ts', 'heroes-styled', 'app.component.ts (styled heroes)')
 
 .l-main-section
   :marked
-    ## Selecting a Hero
-    We have a list of heroes and we have a single hero displayed in our app.
-    The list and the single hero are not connected in any way.
-    We want the user to select a hero from our list, and have the selected hero appear in the details view.
-    This UI pattern is widely known as "master-detail".
-    In our case, the master is the heroes list and the detail is the selected hero.
+    ## Selecting a hero
+    The app now displays a list of heroes as well as a single hero in the details view.
+    The list and the details view are not connected in any way.
+    When the user selects a hero from the list, we want the selected hero to appear in the details view.
+    This UI pattern is known as "master-detail."
+    In this case, the master is the heroes list and the detail is the selected hero.
 
-    Let's connect the master to the detail through a `selectedHero` component property bound to a click event.
+    Let's connect the master to the detail through a `selectedHero` component property, which is bound to a click event.
 
-    ### Click event
-    We modify the `<li>` by inserting an Angular event binding to its click event.
+    ### Add a click event
+    Modify the `<li>` by inserting an Angular event binding to its click event.
 
   +makeExample('toh-2/ts-snippets/app.component.snippets.pt2.ts', 'selectedHero-click', 'app.component.ts (template excerpt)')
 
   :marked
-    Focus on the event binding
+    Focus on the event binding:
   code-example(format="." language="bash").
     (click)="onSelect(hero)"
   :marked
-    The parenthesis identify the `<li>` element's  `click` event as the target.
+    The parentheses identify the `<li>` element's  `click` event as the target.
     The expression to the right of the equal sign calls the  `AppComponent` method, `onSelect()`,
     passing the template input variable `hero` as an argument.
-    That's the same `hero` variable we defined previously in the `ngFor`.
+    That's the same `hero` variable you defined previously in the `ngFor` directive.
   .l-sub-section
     :marked
-      Learn more about Event Binding in the 
+      Learn more about event binding in the 
       [User Input](../guide/user-input.html) and
-      [Templating Syntax](../guide/template-syntax.html#event-binding) chapters.
+      [Templating Syntax](../guide/template-syntax.html#event-binding) pages.
   :marked
     ### Add the click handler
-    Our event binding refers to an `onSelect` method that doesn't exist yet.
-    We'll add that method to our component now.
-
-    What should that method do? It should set the component's selected hero to the hero that the user clicked.
+    <!-- CF: (Sorry for the change in comment style; I can't seem to add a // comment
+    anywhere in this section without commenting out the rest of the section and the next section.)
+    This section title is a verb, making it sound like a task, but it's really an introduction;
+    the tasks it discusses aren't performed until the next section. Would it make sense to merge
+    the two sections and maybe change the title to "Add a click handle to expose the selected hero"? -->
+  
+    Your event binding refers to an `onSelect` method that doesn't exist yet.
+    The `onSelect` method sets the component's selected hero to the hero that the user clicks.
+    You'll add that method to your component shortly.
 
-    Our component doesn't have a “selected hero” yet either. We'll start there.
+    Your component also doesn't have a “selected hero” yet. Let's start there.
 
     ### Expose the selected hero
-
-    We no longer need the static `hero` property of the `AppComponent`.
-    **Replace** it with this simple `selectedHero` property:
+    You no longer need the static `hero` property of the `AppComponent`.
+    Replace it with this simple `selectedHero` property:
 
   +makeExample('toh-2/ts/app/app.component.ts', 'selected-hero', 'app.component.ts (selectedHero)')
-
+  // CF: here I noticed that the hero names disappeared. Would it be helpful to mention that?
+    Perhaps "At this point, you'll notice that the hero names disappear in the browser. Don't 
+    worry, you'll restore them soon."
   :marked
-    We've decided that none of the heroes should be selected before the user picks a hero so
-    we won't initialize the `selectedHero` as we were doing with `hero`.
+    We don't want any of the heroes to be selected before the user picks a hero, so
+    you won't initialize the `selectedHero` as you did with `hero`.
 
-    Now **add an `onSelect` method** that sets the `selectedHero` property to the `hero` the user clicked.
+    Add an `onSelect` method that sets the `selectedHero` property to the `hero` that the user clicks.
   +makeExample('toh-2/ts/app/app.component.ts', 'on-select', 'app.component.ts (onSelect)')
 
   :marked
-    We will be showing the selected hero's details in our template.
-    At the moment, it is still referring to the old `hero` property.
-    Let's fix the template to bind to the new `selectedHero` property.
+    At the moment, the template still refers to the old `hero` property.
+    To change the template to bind to the new `selectedHero` property, update the code as follows:
 
   +makeExample('toh-2/ts-snippets/app.component.snippets.pt2.ts', 'selectedHero-details', 'app.component.ts (template excerpt)')
   :marked
     ### Hide the empty detail with ngIf
 
-    When our app loads we see a list of heroes, but a hero is not selected.
+    When the app loads, you see a list of heroes, but a hero is not selected.
     The `selectedHero` is `undefined`.
-    That's why we'll see the following error in the browser's console:
+    That's why the following error appears in the browser's console:
 
   code-example(language="html").
     EXCEPTION: TypeError: Cannot read property 'name' of undefined in [null]
 
   :marked
-    Remember that we are displaying `selectedHero.name` in the template.
-    This name property does not exist because `selectedHero` itself is undefined.
+    Remember how you're displaying `selectedHero.name` in the template?
+    This name property doesn't exist because `selectedHero` itself is undefined.
 
-    We'll address this problem by keeping the hero detail out of the DOM until there is a selected hero.
+    To address this issue, you'll keep the hero detail out of the DOM until there is a selected hero.
+    <!-- CF: Will readers know what "DOM" means? -->
 
-    We wrap the HTML hero detail content of our template with a `<div>`.
-    Then we add the `ngIf` built-in directive and set it to the `selectedHero` property of our component.
+    Wrap the HTML hero detail content of your template with a `<div>`.
+    Then add the `ngIf` built-in directive and set it to the `selectedHero` property of your component.
 
   +makeExample('toh-2/ts-snippets/app.component.snippets.pt2.ts', 'ng-if', 'app.component.ts (ngIf)')
+  // CF: Would it be helpful to note that now the list of names reappears in the browser?
 
   .alert.is-critical
     :marked
       Remember that the leading asterisk (`*`) in front of `ngIf` is
       a critical part of this syntax.
+  //  CF: is a "critical" type note appropriate here? Could I merge this sentence with
+    the next section?
   :marked
     When there is no `selectedHero`, the `ngIf` directive removes the hero detail HTML from the DOM.
-    There will be no hero detail elements and no bindings to worry about.
+    There are no hero detail elements or bindings to worry about.
 
     When the user picks a hero, `selectedHero` becomes "truthy" and
     `ngIf` puts the hero detail content into the DOM and evaluates the nested bindings.
   .l-sub-section
     :marked
-      `ngIf` and `ngFor` are called “structural directives” because they can change the
+      `ngIf` and `ngFor` are called "structural directives" because they can change the
       structure of portions of the DOM.
       In other words, they give structure to the way Angular displays content in the DOM.
 
-      Learn more about `ngIf`, `ngFor` and other structural directives in the
+      Learn more about `ngIf`, `ngFor`, and other structural directives in the
       [Structural Directives](../guide/structural-directives.html) and
-      [Template Syntax](../guide/template-syntax.html#directives) chapters.
+      [Template Syntax](../guide/template-syntax.html#directives) pages.
 
   :marked
-    The browser refreshes and we see the list of heroes but not the selected hero detail.
+    The browser refreshes and you see the list of heroes but not the selected hero detail.
     The `ngIf` keeps it out of the DOM as long as the `selectedHero` is undefined.
-    When we click on a hero in the list, the selected hero displays in the hero details.
-    Everything is working as we expect.
+    When you click a hero in the list, the selected hero displays in the hero details.
 
     ### Styling the selection
 
-    We see the selected hero in the details area below but we can't quickly locate that hero in the list above.
-    We can fix that by applying the `selected` CSS class to the appropriate `<li>` in the master list.
-    For example, when we select Magneta from the heroes list,
-    we can make it pop out visually by giving it a subtle background color as shown here.
-  //  CF: At this point I already see the background color on the selected hero. 
-    Also, the font in the screen shot doesn't match the sans serif font in my browser (maybe not a big deal).
+    You see the selected hero in the details area, but it's difficult to quickly locate that hero in the list above.
+    You can fix that by applying the `selected` CSS class to the appropriate `<li>` in the master list.
+    For example, when a user selects Magneta from the heroes list,
+    it will pop out with a subtle background color as shown:
 
   figure.image-display
     img(src='/resources/images/devguide/toh/heroes-list-selected.png' alt="Selected hero")
   :marked
-    We'll add a property binding on `class` for the `selected` class to the template. We'll set this to an expression that compares the current `selectedHero` to the `hero`.
+    In the template, you'll add a property binding on `class` for the `selected` class. 
+    You'll set the class to an expression that compares the current `selectedHero` to the `hero`.
 
     The key is the name of the CSS class (`selected`). The value is `true` if the two heroes match and `false` otherwise.
-    We're saying “*apply the `selected` class if the heroes match, remove it if they don't*”.
+    You're saying “*apply the `selected` class if the heroes match, and remove it if they don't*”.
   +makeExample('toh-2/ts-snippets/app.component.snippets.pt2.ts', 'class-selected-1', 'app.component.ts (setting the CSS class)')(format=".")
   :marked
-    Notice in the template that the `class.selected` is surrounded in square brackets (`[]`).
-    This is the syntax for a **property binding**, a binding in which data flows one way
+    Notice that `class.selected` is surrounded by square brackets (`[]`).
+    This is the syntax for a *property binding*, in which data flows one way
     from the data source (the expression `hero === selectedHero`) to a property of `class`.
   +makeExample('toh-2/ts-snippets/app.component.snippets.pt2.ts', 'class-selected-2', 'app.component.ts (styling each hero)')(format=".")
 
   .l-sub-section
     :marked
       Learn more about [property bindings](../guide/template-syntax.html#property-binding)
-      in the Template Syntax chapter.
+      in the Template Syntax page.
 
   :marked
-    The browser reloads our app.
-    We select the hero Magneta and the selection is clearly identified by the background color.
+    The browser reloads your app.
+    Click the hero Magneta. Your selection is clearly identified by the background color.
 
   figure.image-display
     img(src='/resources/images/devguide/toh/heroes-list-1.png' alt="Output of heroes list app")
-  //  CF: The font in the screen shot doesn't match the sans serif font in my browser output.
 
   :marked
-    We select a different hero and the tell-tale color switches to that hero.
+    Click a different hero name and the selection color switches to that hero.
 
     Here's the complete `app.component.ts` as it stands now:
 
@@ -299,17 +307,17 @@ code-example(language="bash").
 
 .l-main-section
 :marked
-  ## The Road We've Travelled
-  Here's what we achieved in this chapter:
+  ## The road you've travelled
+  Here's what you achieved in this page:
 
-  * Our Tour of Heroes now displays a list of selectable heroes
-  * We added the ability to select a hero and show the hero's details
-  * We learned how to use the built-in directives `ngIf` and `ngFor` in a component's template
+  * Your Tour of Heroes app now displays a list of selectable heroes.
+  * You added the ability to select a hero and show the hero's details.
+  * You learned how to use the built-in directives `ngIf` and `ngFor` in a component's template.
 
-  Run the <live-example></live-example> for this part.
+  **Try it out**. Here's a link to a <live-example></live-example>.
 
-  ### The Road Ahead
-  Our Tour of Heroes has grown, but it's far from complete.
-  We can't put the entire app into a single component.
-  We need to break it up into sub-components and teach them to work together
-  as we learn in the [next chapter](toh-pt3.html).
+  ## The road ahead
+  Your Tour of Heroes app has grown, but it's far from complete.
+  You can't put the entire app into a single component.
+  <!-- CF: It's not clear to me why you can't put it into a single component. Is this sentence necessary? -->
+  In the [next page](toh-pt3.html), you'll split the app into sub-components and make them work together.