Guide & Features edits (#2180)

* Guide & Features edits

* PR updates & Architecture edits

* a couple we -> you updates

* architecture edits

* copy edits in arch., index, npm-packages

* few copy edits

* some chapter -> page changes

README.md

@@ -71,7 +71,7 @@ If you are only going to work on a specific part of the docs, such as the dev gu
 ## Code Sample Development
 
 All documentation is supported by sample code and plunkers. 
-Such code resides in the `public/docs/_examples` directory, under chapter-specific directories, further divided by language track.
+Such code resides in the `public/docs/_examples` directory, under page-specific directories, further divided by language track.
 
 For example, the TypeScript QuickStart sample is in `public/docs/_examples/quickstart/ts`.
 

public/docs/js/latest/guide/forms-deprecated.jade

@@ -208,7 +208,7 @@ code-example(format="").
   **We are not using Angular yet**. There are no bindings. No extra directives. Just layout.
 
   The `container`,`form-group`, `form-control`, and `btn` classes 
-  come from [Twitter Boostrap](http://getbootstrap.com/css/). Purely cosmetic.
+  come from [Twitter Bootstrap](http://getbootstrap.com/css/). Purely cosmetic.
   We're using Bootstrap to gussy up our form.
   Hey, what's a form without a little style!
 

public/docs/js/latest/guide/forms.jade

@@ -224,7 +224,7 @@ code-example(format="").
   **We are not using Angular yet**. There are no bindings. No extra directives. Just layout.
 
   The `container`,`form-group`, `form-control`, and `btn` classes 
-  come from [Twitter Boostrap](http://getbootstrap.com/css/). Purely cosmetic.
+  come from [Twitter Bootstrap](http://getbootstrap.com/css/). Purely cosmetic.
   We're using Bootstrap to gussy up our form.
   Hey, what's a form without a little style!
 

public/docs/ts/_cache/glossary.jade

@@ -32,7 +32,7 @@ block includes
   .l-sub-section
     :marked
       Angular applications can be compiled by developers at build-time.
-      By compiling your application using the compiler-cli, `ngc`, you can boostrap directly
+      By compiling your application using the compiler-cli, `ngc`, you can bootstrap directly
       to a Module Factory, meaning you don't need to include the Angular compiler in your javascript bundle.
       Ahead of Time compiled applications also benefit from decreased load time and increased performance.
 

public/docs/ts/latest/glossary.jade

@@ -32,7 +32,7 @@ block includes
   .l-sub-section
     :marked
       Angular applications can be compiled by developers at build-time.
-      By compiling your application using the compiler-cli, `ngc`, you can boostrap directly
+      By compiling your application using the compiler-cli, `ngc`, you can bootstrap directly
       to a Module Factory, meaning you don't need to include the Angular compiler in your javascript bundle.
       Ahead of Time compiled applications also benefit from decreased load time and increased performance.
 

public/docs/ts/latest/guide/_data.json

@@ -115,7 +115,7 @@
 
   "npm-packages": {
     "title": "Npm Packages",
-    "intro": "Details of the recommended npm packages and the different kinds of package dependencies"
+    "intro": "Recommended npm packages, and how to specify package dependencies"
   },
 
   "pipes": {

public/docs/ts/latest/guide/architecture.jade

@@ -4,25 +4,24 @@ block includes
   - var _at_angular = '@angular'
 
 :marked
-  Angular 2 is a framework to help us build client applications in HTML and
+  Angular 2 is a framework for building client applications in HTML and
   either JavaScript or a language (like Dart or TypeScript) that compiles to JavaScript.
 
 block angular-parts
   :marked
-    The framework consists of several cooperating libraries, some of them core and some optional.
+    The framework consists of several libraries, some of them core and some optional.
 
 :marked
-  We write Angular applications by composing HTML *templates* with Angularized-markup,
+  You write Angular applications by composing HTML *templates* with Angularized markup,
   writing *component* classes to manage those templates, adding application logic in *services*,
   and boxing components and services in *modules*.
   
-  Then we launch the app by *bootstrapping* the top _root module_.
+  Then you launch the app by *bootstrapping* the _root module_.
-  Angular takes over, presenting our application content in a browser and
+  Angular takes over, presenting your application content in a browser and
-  responding to user interactions according to the instructions we provided.
+  responding to user interactions according to the instructions you've provided.
 
-  Of course there is more to it than this.
+  Of course, there is more to it than this.
-  We'll learn the details when we dive into the guide chapters.
+  You'll learn the details in the pages that follow. For now, focus on the big picture.
-  Let's get the big picture first.
 
 figure
   img(src="/resources/images/devguide/architecture/overview2.png" alt="overview" style="margin-left:-40px;" width="700")
@@ -30,19 +29,19 @@ figure
 :marked
   The architecture diagram identifies the eight main building blocks of an Angular 2 application:
 
-  1. [Modules](#modules)
+  * [Modules](#modules)
-  1. [Components](#components)
+  * [Components](#components)
-  1. [Templates](#templates)
+  * [Templates](#templates)
-  1. [Metadata](#metadata)
+  * [Metadata](#metadata)
-  1. [Data binding](#data-binding)
+  * [Data binding](#data-binding)
-  1. [Directives](#directives)
+  * [Directives](#directives)
-  1. [Services](#services)
+  * [Services](#services)
-  1. [Dependency injection](#dependency-injection)
+  * [Dependency injection](#dependency-injection)
 
-  Learn these, and we're on our way.
+  Learn these building blocks, and you're on your way.
 
 .l-sub-section
-  p The code referenced in this chapter is available as a #[+liveExampleLink2()].
+  p The code referenced on this page is available as a #[+liveExampleLink2()].
 
 .l-main-section
 :marked
@@ -50,18 +49,18 @@ figure
 figure
   img(src="/resources/images/devguide/architecture/module.png" alt="Component" align="left" style="width:240px; margin-left:-40px;margin-right:10px" )
 :marked
-  Angular apps are modular and Angular has its own modularity system called _Angular Modules_ or _NgModules_.
+  Angular apps are modular and Angular has its own modularity system called _Angular modules_ or _NgModules_.
 
-  _Angular Modules_ are a big deal. 
+  _Angular modules_ are a big deal. 
-  We can only introduce them here; the [Angular Modules](ngmodule.html) chapter covers modules in depth.
+  This page introduces modules; the [Angular modules](ngmodule.html) page covers them in depth.
 
 <br clear="all"><br>
 :marked
   Every Angular app has at least one module, the _root module_, conventionally named `AppModule`.
 
-  While the _root_ module may be the only module in a small application, most apps have many more 
+  While the _root module_ may be the only module in a small application, most apps have many more 
-  _feature_ modules, each a cohesive block of code dedicated to an application domain,
+  _feature modules_, each a cohesive block of code dedicated to an application domain,
-  a workflow, or a closely-related set of capabilities. 
+  a workflow, or a closely related set of capabilities. 
 
   An Angular module, whether a _root_ or _feature_, is a class with an `@NgModule` decorator.
 .l-sub-section
@@ -73,18 +72,18 @@ figure
     Learn more</a> about decorators on the web.
 :marked
   `NgModule` is a decorator function that takes a single metadata object whose properties describe the module. 
-  The most important are
+  The most important properties are:
   * `declarations` - the _view classes_ that belong to this module.
-  Angular has three kinds of view classes: [components](#components), [directives](#directives) and [pipes](pipes.html).
+  Angular has three kinds of view classes: [components](#components), [directives](#directives), and [pipes](pipes.html).
 
-  * `exports` - subset of declarations that should be visible and usable in the component [templates](#templates) of other modules.
+  * `exports` - the subset of declarations that should be visible and usable in the component [templates](#templates) of other modules.
 
   * `imports` - other modules whose exported classes are needed by component templates declared in _this_ module.
 
-  * `providers` creators of [services](#services) that this module contributes to
+  * `providers` - creators of [services](#services) that this module contributes to
   the global collection of services; they become accessible in all parts of the app.
 
-  * `bootstrap` - identifies the main application view, called the _root component_, 
+  * `bootstrap` - the main application view, called the _root component_, 
   that hosts all other app views. Only the _root module_ should set this `bootstrap` property.
 
   Here's a simple root module:
@@ -92,21 +91,17 @@ figure
 
 .l-sub-section
   :marked
-    The `export` of `AppComponent` is just for show.
+    The `export` of `AppComponent` is just to show how to export; it isn't actually necessary in this example. A root module has no reason to _export_ anything because other components don't need to _import_ the root module. 
-    A root module has no reason to export anything because ... it's the root. 
-    We don't expect other modules to import the root module.
-
-    But if one did, it could use the `AppComponent` in its component templates.
 :marked
-  We launch an application by _bootstrapping_ its root module. 
+  Launch an application by _bootstrapping_ its root module. 
-  During development we're likely to bootstrap the `AppModule` in a `main.ts` file like this one.
+  During development you're likely to bootstrap the `AppModule` in a `main.ts` file like this one.
     
 +makeExample('app/main.ts', '', 'app/main.ts')(format='.')
 
 :marked
-  ### Angular Modules vs. JavaScript Modules
+  ### Angular modules vs. JavaScript modules
 
-  The Angular module &mdash; a class decorated with `@NgModule` &mdash; is a fundamental feature of Angular itself.
+  The Angular module &mdash; a class decorated with `@NgModule` &mdash; is a fundamental feature of Angular.
 
   JavaScript also has its own module system for managing collections of JavaScript objects.
   It's completely different and unrelated to the Angular module system.
@@ -122,39 +117,38 @@ figure
   :marked
     <a href="http://exploringjs.com/es6/ch_modules.html" target="_blank">Learn more about the JavaScript module system on the web.</a>
 :marked
-  These are two different and _complementary_ module systems. We use them both to write our apps.
+  These are two different and _complementary_ module systems. Use them both to write your apps.
 
-  ### Angular Libraries
+  ### Angular libraries
 
 figure
   img(src="/resources/images/devguide/architecture/library-module.png" alt="Component" align="left" style="width:240px; margin-left:-40px;margin-right:10px" )
 
 :marked
-  Angular itself ships as a collection of JavaScript modules. We can think of them as library modules. 
+  Angular ships as a collection of JavaScript modules. You can think of them as library modules. 
 
-  Each Angular library name begin with the `!{_at_angular}` prefix.
+  Each Angular library name begins with the `!{_at_angular}` prefix.
   
-  We install them with the **npm** package manager and import parts of them with JavaScript `import` statements.
+  You install them with the **npm** package manager and import parts of them with JavaScript `import` statements.
 <br clear="all"><br>
 :marked
-  For example, we import Angular's `Component` decorator from the `@angular/core` library like this:
+  For example, import Angular's `Component` decorator from the `@angular/core` library like this:
 +makeExample('app/app.component.ts', 'import', '')(format='.')
 :marked
-  We also import Angular _modules_ from Angular _libraries_ using JavaScript import statements:
+  You also import Angular _modules_ from Angular _libraries_ using JavaScript import statements:
 +makeExample('app/mini-app.ts', 'import-browser-module', '')(format='.')
 :marked
-  Our application module needs material from within that `BrowserModule`
+  In the example of the simple root module above, the application module needs material from within that `BrowserModule`. To access that material, add it to the `@NgModule` metadata `imports` like this.
-  so we add it to the `@NgModule` metadata `imports` like this.
 +makeExample('app/mini-app.ts', 'ngmodule-imports', '')(format='.')
 :marked
-  We're using both the Angular and JavaScript module systems _together_.
+  In this way you're using both the Angular and JavaScript module systems _together_.
 
   It's easy to confuse the two systems because they share the common vocabulary of "imports" and "exports".
-  Hang in there. The confusion will yield to clarity with time and experience.
+  Hang in there. The confusion yields to clarity with time and experience.
 
 .l-sub-section
   :marked
-    Learn more in the [Angular Modules](ngmodule.html) chapter.
+    Learn more from the [Angular modules](ngmodule.html) page.
 
 .l-hr 
 
@@ -165,28 +159,27 @@ figure
   img(src="/resources/images/devguide/architecture/hero-component.png" alt="Component" align="left" style="width:200px; margin-left:-40px;margin-right:10px" )
 
 :marked
-  A **component** controls a patch of screen real estate that we could call a *view*.
+  A _component_ controls a patch of screen called a *view*.
-  The shell at the application root with navigation links, a list of heroes, a hero editor ...
-  they're all views controlled by components.
 
-  We define a component's application logic &mdash; what it does to support the view &mdash; inside a class.
+  For example, the following views are controlled by components:
+
+  * The app root with the navigation links.
+  * The list of heroes.
+  * The hero editor.
+
+
+  You define a component's application logic&mdash;what it does to support the view&mdash;inside a class.
   The class interacts with the view through an API of properties and methods.
 
   <a id="component-code"></a>
-  A `HeroListComponent`, for example, might have a `heroes` property that returns !{_an} !{_array} of heroes
+  For example, this `HeroListComponent` has a `heroes` property that returns !{_an} !{_array} of heroes
-  that it acquired from a service.
+  that it acquires from a service.
-  It might have a `selectHero()` method that sets a `selectedHero` property when the user clicks to choose a hero from that list.
+  `HeroListComponent` also has a `selectHero()` method that sets a `selectedHero` property when the user clicks to choose a hero from that list.
-  The component might be a class like this:
 
 +makeExcerpt('app/hero-list.component.ts', 'class')
 :marked
   Angular creates, updates, and destroys components as the user moves through the application.
-  The developer can take action at each moment in this lifecycle through optional [lifecycle hooks](lifecycle-hooks.html), like `ngOnInit()` declared above.
+  Your app can take action at each moment in this lifecycle through optional [lifecycle hooks](lifecycle-hooks.html), like `ngOnInit()` declared above.
-.l-sub-section
-  :marked
-    We may wonder who is calling the component's constructor? Who provides the service parameter?
-    For the moment, have faith that Angular will call the constructor and deliver an
-    appropriate `HeroService` when we need it.
 
 .l-hr 
 
@@ -196,26 +189,21 @@ figure
 figure
   img(src="/resources/images/devguide/architecture/template.png" alt="Template" align="left" style="width:200px; margin-left:-40px;margin-right:10px" )
 :marked
-  We define a component's view with its companion **template**. A template is a form of HTML
+  You define a component's view with its companion **template**. A template is a form of HTML
   that tells Angular how to render the component.
 
-  A template looks like regular HTML much of the time ... and then it gets a bit strange. Here is a
+  A template looks like regular HTML, except for a few differences. Here is a
   template for our `HeroListComponent`:
 
 +makeExample('app/hero-list.component.html')
 
 :marked
-  This template features typical HTML elements like `<h2>` and  `<p>`.
+  Although this template uses typical HTML elements like `<h2>` and  `<p>`, it also has some differences. Code like `*ngFor`, `{{hero.name}}`, `(click)`, `[hero]`, and `<hero-detail>` uses Angular's [template syntax](template-syntax.html).
-  But what are `*ngFor`, `{{hero.name}}`, `(click)`, `[hero]`, and `<hero-detail>`?
 
-  These are examples of Angular's [template syntax](template-syntax.html).
-  We will grow accustomed to that syntax and may even learn to love it.
-  We'll begin to explain it in a moment.
 
-  Before we do, focus attention on the last line.
+  In the last line of the template, the `<hero-detail>` tag is a custom element that represents a new component, `HeroDetailComponent`.
-  The `<hero-detail>` tag is a custom element representing the `HeroDetailComponent`.
   
-  The `HeroDetailComponent` is a *different* component than the `HeroListComponent` we've been reviewing.
+  The `HeroDetailComponent` is a *different* component than the `HeroListComponent` you've been reviewing.
   The `HeroDetailComponent` (code not shown) presents facts about a particular hero, the
   hero that the user selects from the list presented by the `HeroListComponent`.
   The `HeroDetailComponent` is a **child** of the `HeroListComponent`.
@@ -223,10 +211,8 @@ figure
 figure
   img(src="/resources/images/devguide/architecture/component-tree.png" alt="Metadata" align="left" style="width:300px; margin-left:-40px;margin-right:10px" )
 :marked
-  Notice how `<hero-detail>` rests comfortably among native HTML elements.
+  Notice how `<hero-detail>` rests comfortably among native HTML elements. Custom components mix seamlessly with native HTML in the same layouts.
-  We can and _will_ mix our custom components with native HTML in the same layouts.
 
-  In this manner we'll compose complex component trees to build out our richly featured application.
 <br clear="all">
 
 .l-hr 
@@ -241,20 +227,20 @@ figure
 <p style="padding-top:10px">Metadata tells Angular how to process a class.</p>
 <br clear="all">
 :marked
-  [Looking back at the code](#component-code) for `HeroListComponent`, we see that it's just a class.
+  [Looking back at the code](#component-code) for `HeroListComponent`, you can see that it's just a class.
   There is no evidence of a framework, no "Angular" in it at all.
 
-  In fact, it really is *just a class*. It's not a component until we *tell Angular about it*.
+  In fact, `HeroListComponent` really is *just a class*. It's not a component until you *tell Angular about it*.
 
-  We tell Angular that `HeroListComponent` is a component by attaching **metadata** to the class.
+  To tell Angular that `HeroListComponent` is a component, attach **metadata** to the class.
 
-  In !{_Lang}, we attach metadata by using !{_a} **!{_decorator}**.
+  In !{_Lang}, you attach metadata by using !{_a} **!{_decorator}**.
   Here's some metadata for `HeroListComponent`:
 
 +makeExcerpt('app/hero-list.component.ts', 'metadata')
 
 :marked
-  Here we see the `@Component` !{_decorator} which (no surprise) identifies the class
+  Here is the `@Component` !{_decorator}, which identifies the class
   immediately below it as a component class.
 
 block ts-decorator
@@ -270,32 +256,30 @@ block ts-decorator
   For example, if an app's  HTML contains `<hero-list></hero-list>`, then
   Angular inserts an instance of the `HeroListComponent` view between those tags.
 
-  - `templateUrl`: address of this component's template, which we showed [above](#templates).
+  - `templateUrl`: address of this component's HTML template, shown [above](#templates).
 
   - `directives`: !{_array} of the components or directives that *this* template requires.
-  We saw in the last line of our template that we expect Angular to insert a `HeroDetailComponent`
+  In the last line of `hero-list.component.html`, Angular inserts a `HeroDetailComponent`
   in the space indicated by `<hero-detail>` tags.
-  Angular will do so only if we mention the `HeroDetailComponent` in this `directives` !{_array}.
+  Angular does so only if `HeroDetailComponent` is in this `directives` !{_array}.
 
   - `providers`: !{_array} of **dependency injection providers** for services that the component requires.
-  This is one way to tell Angular that our component's constructor requires a `HeroService`
+  This is one way to tell Angular that the component's constructor requires a `HeroService`
-  so it can get the list of heroes to display. We'll get to dependency injection later.
+  so it can get the list of heroes to display. 
 
 figure
   img(src="/resources/images/devguide/architecture/template-metadata-component.png" alt="Metadata" align="left" style="height:200px; margin-left:-40px;margin-right:10px" )
 
 :marked
-  Angular reads the metadata specified by the `@Component`
+  The metadata in the `@Component` tells Angular where to get the major building blocks you specify for the component.
-  annotation. That's how Angular learns to do "the right thing".
 
   The template, metadata, and component together describe a view.
 
-  We apply other metadata !{_decorator}s in a similar fashion to guide Angular behavior.
+  Apply other metadata !{_decorator}s in a similar fashion to guide Angular behavior.
-  `@Injectable`, `@Input`, and `@Output` are a few of the more popular !{_decorator}s
+  `@Injectable`, `@Input`, and `@Output` are a few of the more popular !{_decorator}s.
-  we'll master as our Angular knowledge grows.
 <br clear="all">
 :marked
-  The architectural takeaway is that we must add metadata to our code
+  The architectural takeaway is that you must add metadata to your code
   so that Angular knows what to do.
 
 .l-hr 
@@ -303,7 +287,7 @@ figure
 .l-main-section
 :marked
   ## Data binding
-  Without a framework, we would be responsible for pushing data values into the HTML controls and turning user responses
+  Without a framework, you would be responsible for pushing data values into the HTML controls and turning user responses
   into actions and value updates. Writing such push/pull logic by hand is tedious, error-prone, and a nightmare to
   read as any experienced jQuery programmer can attest.
 figure
@@ -311,13 +295,12 @@ figure
 :marked
   Angular supports **data binding**,
   a mechanism for coordinating parts of a template with parts of a component.
-  We add binding markup to the template HTML to tell Angular how to connect both sides.
+  Add binding markup to the template HTML to tell Angular how to connect both sides.
 
-  There are four forms of data binding syntax. Each form has a direction &mdash; to the DOM, from the DOM, or in both directions &mdash;
+  As the diagram shows, there are four forms of data binding syntax. Each form has a direction &mdash; to the DOM, from the DOM, or in both directions.
-  as indicated by the arrows in the diagram.
 <br clear="all">
 :marked
-  We saw three forms of data binding in our [example](#templates) template:
+  The `HeroListComponent` [example](#templates) template has three forms:
 
 +makeExcerpt('app/hero-list.component.1.html', 'binding')
 
@@ -332,8 +315,7 @@ figure
 
   **Two-way data binding** is an important fourth form
   that combines property and event binding in a single notation, using the `ngModel` directive.
-  We didn't have a two-way binding in the `HeroListComponent` template;
+  Here's an example from the `HeroDetailComponent` template:
-  here's an example from the `HeroDetailComponent` template:
 
 +makeExcerpt('app/hero-detail.component.html', 'ngModel')
 
@@ -343,13 +325,12 @@ figure
   as with event binding.
 
   Angular processes *all* data bindings once per JavaScript event cycle,
-  from the root of the application component tree down to the leaves.
+  from the root of the application component tree through all child components.
 
 figure
   img(src="/resources/images/devguide/architecture/component-databinding.png" alt="Data Binding" style="float:left; width:300px; margin-left:-40px;margin-right:10px" )
 :marked
-  We don't know all the details yet,
+  Data binding plays an important role in communication
-  but it's clear from these examples that data binding plays an important role in communication
   between a template and its component.
 <br clear="all">
 figure
@@ -369,18 +350,17 @@ figure
   Angular templates are *dynamic*. When Angular renders them, it transforms the DOM
   according to the instructions given by **directives**.
 
-  A directive is a class with directive metadata. In !{_Lang} we apply the `@Directive` !{_decorator}
+  A directive is a class with directive metadata. In !{_Lang}, apply the `@Directive` !{_decorator}
   to attach metadata to the class.
 <br clear="all">
 :marked
-  We already met one form of directive: the component. A component is a *directive-with-a-template*;
+  A component is a *directive-with-a-template*;
   a `@Component` !{_decorator} is actually a `@Directive` !{_decorator} extended with template-oriented features.
 
 .l-sub-section
   :marked
     While **a component is technically a directive**,
-    components are so distinctive and central to Angular applications that we chose
+    components are so distinctive and central to Angular applications that this architectural overview  separates components from directives.
-    to separate components from directives in this architectural overview.
 :marked
   Two *other* kinds of directives exist: _structural_ and _attribute_ directives.
 
@@ -389,7 +369,7 @@ figure
 
   **Structural** directives alter layout by adding, removing, and replacing elements in DOM.
 
-  Our [example](#templates) template uses two built-in structural directives:
+  The [example template](#templates) uses two built-in structural directives:
 
 +makeExcerpt('app/hero-list.component.1.html', 'structural')
 
@@ -411,12 +391,12 @@ block dart-bool
 
 +makeExcerpt('app/hero-detail.component.html', 'ngModel')
 :marked
-  Angular ships with a small number of other directives that either alter the layout structure
+  Angular has a few more directives that either alter the layout structure
   (for example, [ngSwitch](template-syntax.html#ngSwitch))
   or modify aspects of DOM elements and components
   (for example, [ngStyle](template-syntax.html#ngStyle) and [ngClass](template-syntax.html#ngClass)).
 
-  Of course, we can also write our own directives. Components such as
+  Of course, you can also write your own directives. Components such as
   `HeroListComponent` are one kind of custom directive.
   <!-- PENDING: link to where to learn more about other kinds! -->
 
@@ -428,7 +408,7 @@ block dart-bool
 figure
   img(src="/resources/images/devguide/architecture/service.png" alt="Service" style="float:left; margin-left:-40px;margin-right:10px" )
 :marked
-  _Service_ is a broad category encompassing any value, function, or feature that our application needs.
+  _Service_ is a broad category encompassing any value, function, or feature that your application needs.
 
   Almost anything can be a service.
   A service is typically a class with a narrow, well-defined purpose. It should do something specific and do it well.
@@ -441,12 +421,12 @@ figure
   * tax calculator
   * application configuration
 
-  There is nothing specifically _Angular_ about services. Angular itself has no definition of a service.
+  There is nothing specifically _Angular_ about services. Angular has no definition of a service.
   There is no service base class, and no place to register a service.
 
-  Yet services are fundamental to any Angular application. Our components are big consumers of services.
+  Yet services are fundamental to any Angular application. Components are big consumers of services.
 
-  Here's an example of a service class that logs to the browser console
+  Here's an example of a service class that logs to the browser console:
 
 +makeExcerpt('app/logger.service.ts', 'class')
 
@@ -459,8 +439,8 @@ figure
 :marked
   Services are everywhere.
 
-  We prefer our component classes lean. Our components don't fetch data from the server,
+  Component classes should be lean. They don't fetch data from the server,
-  they don't validate user input, and they don't log directly to the console.
+  validate user input, or log directly to the console.
   They delegate such tasks to services.
 
   A component's job is to enable the user experience and nothing more. It mediates between the view (rendered by the template)
@@ -469,9 +449,9 @@ figure
   It delegates everything nontrivial to services.
 
   Angular doesn't *enforce* these principles.
-  It won't complain if we write a "kitchen sink" component with 3000 lines.
+  It won't complain if you write a "kitchen sink" component with 3000 lines.
 
-  Angular does help us *follow* these principles by making it easy to factor our
+  Angular does help you *follow* these principles by making it easy to factor your
   application logic into services and make those services available to components through *dependency injection*.
 
 .l-hr 
@@ -488,7 +468,7 @@ figure
 <br clear="all">
 :marked
   Angular can tell which services a component needs by looking at the types of its constructor parameters.
-  For example, the constructor of our `HeroListComponent` needs a `HeroService`:
+  For example, the constructor of your `HeroListComponent` needs a `HeroService`:
 
 +makeExcerpt('app/hero-list.component.ts (constructor)', 'ctor')
 
@@ -501,7 +481,7 @@ figure
   before returning the service to Angular.
   When all requested services have been resolved and returned,
   Angular can call the component's constructor with those services as arguments.
-  This is what we mean by *dependency injection*.
+  This is *dependency injection*.
 
   The process of `HeroService` injection looks a bit like this:
 figure
@@ -509,27 +489,27 @@ figure
 :marked
   If the injector doesn't have a `HeroService`, how does it know how to make one?
 
-  In brief, we must have previously registered a **provider** of the `HeroService` with the injector.
+  In brief, you must have previously registered a **provider** of the `HeroService` with the injector.
   A provider is something that can create or return a service, typically the service class itself.
 
-  We can register providers in modules or in components.
+  You can register providers in modules or in components.
   
-  We often add providers to the [root module](#module) so that
+  In general, add providers to the [root module](#module) so that
   the same instance of a service is available everywhere.
 
 +makeExample('app/app.module.ts', 'providers', 'app/app.module.ts (module providers)')(format='.')
 
 :marked
-  Alternatively, we might register at a component level in the `providers` property of the `@Component` metadata:
+  Alternatively, register at a component level in the `providers` property of the `@Component` metadata:
 
 +makeExample('app/hero-list.component.ts', 'providers', 'app/hero-list.component.ts (component providers)')(format='.')
 
 :marked
-  Registering at a component level means we get a new instance of the
+  Registering at a component level means you get a new instance of the
   service with each new instance of that component.
 
   <!-- We've vastly oversimplified dependency injection for this overview.
-  The full story is in the [Dependency Injection](dependency-injection.html) chapter. -->
+  The full story is in the [dependency injection](dependency-injection.html) page. -->
 
   Points to remember about dependency injection:
 
@@ -541,7 +521,7 @@ figure
 
   * A *provider* is a recipe for creating a service.
 
-  * We register *providers* with injectors.
+  * Register *providers* with injectors.
 
 .l-hr 
 
@@ -549,44 +529,41 @@ figure
 :marked
   ## Wrap up
 
-  We've learned just a bit about the eight main building blocks of an Angular application:
+  You've learned the basics about the eight main building blocks of an Angular application:
 
-  1. [Modules](#modules)
+  * [Modules](#modules)
-  1. [Components](#components)
+  * [Components](#components)
-  1. [Templates](#templates)
+  * [Templates](#templates)
-  1. [Metadata](#metadata)
+  * [Metadata](#metadata)
-  1. [Data binding](#data-binding)
+  * [Data binding](#data-binding)
-  1. [Directives](#directives)
+  * [Directives](#directives)
-  1. [Services](#services)
+  * [Services](#services)
-  1. [Dependency injection](#dependency-injection)
+  * [Dependency injection](#dependency-injection)
 
   That's a foundation for everything else in an Angular application,
   and it's more than enough to get going.
-  But it doesn't include everything we'll need or want to know.
+  But it doesn't include everything you need to know.
 
   Here is a brief, alphabetical list of other important Angular features and services.
-  Most of them are covered in this Developers Guide (or soon will be).
+  Most of them are covered in this documentation (or soon will be).
 
-  > [**Animations**](animations.html): The animation library makes it easy for developers to animate component behavior
+  > [**Animations**](animations.html): Animate component behavior
-  without deep knowledge of animation techniques or CSS.
+  without deep knowledge of animation techniques or CSS with Angular's animation library.
 
-  > **Change detection**: Learn how Angular decides that a component property value has changed and
+  > **Change detection**: The change detection documentation will cover how Angular decides that a component property value has changed,
-  when to update the screen.
+  when to update the screen, and how it uses **zones** to intercept asynchronous activity and run its change detection strategies.
-  Learn how it uses **zones** to intercept asynchronous activity and run its change detection strategies.
 
-  > **Events**: The DOM raises events. So can components and services. Angular offers mechanisms for
+  > **Events**: The events documentation will cover how to use components and services to raise events with mechanisms for
   publishing and subscribing to events.
 
   > [**Forms**](forms.html): Support complex data entry scenarios with HTML-based validation and dirty checking.
 
   > [**HTTP**](server-communication.html): Communicate with a server to get data, save data, and invoke server-side actions with an HTTP client.
 
-  > [**Lifecycle hooks**](lifecycle-hooks.html): We can tap into key moments in the lifetime of a component, from its creation to its destruction,
+  > [**Lifecycle hooks**](lifecycle-hooks.html): Tap into key moments in the lifetime of a component, from its creation to its destruction,
   by implementing the lifecycle hook interfaces.
 
-  > [**Pipes**](pipes.html): Services that transform values for display.
+  > [**Pipes**](pipes.html): Use pipes in your templates to improve the user experience by transforming values for display. Consider this `currency` pipe expression:
-  We can put pipes in our templates to improve the user experience. Consider
-  this `currency` pipe expression:
 <div style="margin-left:40px">
 code-example().
   price | currency:'USD':true
@@ -597,6 +574,6 @@ code-example().
   > [**Router**](router.html): Navigate from page to page within the client
     application and never leave the browser.
 
-  > [**Testing**](testing.html): Angular provides a
+  > [**Testing**](testing.html): Run unit tests with Angular's 
   [testing library](https://pub.dartlang.org/packages/angular2_testing)
-  to run unit tests on our application parts as they interact with the Angular framework.
+   on your application parts as they interact with the Angular framework.

public/docs/ts/latest/guide/index.jade

@@ -9,8 +9,6 @@ figure
   This is a practical guide to Angular for experienced programmers who
   are building client applications in HTML and #{langName}.
 
-  We are on a journey together to understand how Angular works and, more importantly,
-  how to make it work for us.  This overview begins the journey.
   <br clear="all">
 // #enddocregion intro
 
@@ -20,7 +18,7 @@ figure
   # Organization
 
   The documentation is divided into major thematic sections, each
-  a collection of chapters devoted to that theme.
+  a collection of pages devoted to that theme.
 // #enddocregion how-to-read-1
 // #docregion how-to-read-2
 - var top="vertical-align:top"
@@ -31,7 +29,7 @@ table(width="100%")
     td <b>QuickStart</b>
     td
       :marked
-        The foundation for every chapter and sample in this documentation.
+        The foundation for every page and sample in this documentation.
   tr(style=top)
     td <b>Tutorial</b>
     td
@@ -60,55 +58,50 @@ table(width="100%")
         Authoritative details about each member of the Angular libraries.
 :marked
   # Learning path
-  We don't have to read the guide straight through.  Most chapters stand on their own.
+  You don't have to read the guide straight through.  Most pages stand on their own.
 
-  We recommend a learning path for those new to Angular.
+  For those new to Angular, the recommended learning path runs through the *Basics* section:
-  Most of that path runs through the *Basics* section:
 
-  1. Read the [Architecture](architecture.html) overview to get the big picture.
+  1. For the big picture, read the [Architecture](architecture.html) overview.
 
-  1. Try the [QuickStart](../quickstart.html). The QuickStart is the "Hello, World" of Angular 2.
+  1. Try [QuickStart](../quickstart.html). QuickStart is the "Hello, World" of Angular 2.
-  It shows us how to set up the libraries and tools we'll need to write *any* Angular app.
+  It shows you how to set up the libraries and tools you'll need to write *any* Angular app.
 
-  1. Take the *Tour of Heroes* [Tutorial](../tutorial), which picks up from where the QuickStart leaves off
+  1. Take the *Tour of Heroes* [tutorial](../tutorial), which picks up where QuickStart leaves off,
-  and builds a simple data-driven app.
+  and builds a simple data-driven app. The app demonstrates the essential characteristics of a professional application:
-  Simple, yes, but with the essential characteristics we'd expect of a professional application:
   a sensible project structure, data binding, master/detail, services, dependency injection, navigation, and remote data access.
 
-    Return to the *Basics* section and continue in the suggested order:
+  1. [Displaying Data](displaying-data.html) explains how to display information on the screen.
 
-  1. [Displaying Data](displaying-data.html) explains how to get information on to the screen.
+  1. [User Input](user-input.html) covers how Angular responds to user behavior.
 
-  1. [User Input](user-input.html) covers the basics of responding to user behavior.
+  1. [Forms](forms.html) handles user data entry and validation within the UI.
 
-  1. [Forms](forms.html) handle user data entry and validation within the UI.
+  1. [Dependency Injection](dependency-injection.html) is the way to build large, maintainable applications
-
-  1. [Dependency Injection](dependency-injection.html) is the way we build large, maintainable applications
   from small, single-purpose parts.
 
   1. [Template Syntax](template-syntax.html) is a comprehensive study of Angular template HTML.
 
-  With this foundation, we can read and understand any chapter in the guide.
+  After reading the above sections, you can skip to any other pages on this site.
 // #enddocregion how-to-read-2
 // #docregion the-rest
 :marked
   # Code samples
 
-  Every chapter includes code snippets that we can reuse in our own applications.
+  Each page includes code snippets that you can reuse in your applications.
-  These snippets are excerpts from a sample application that accompanies the chapter.
+  These snippets are excerpts from a sample application that accompanies the page.
 
 block example-links
   :marked
     Look for a link to a running version of that sample near the top of each page,
-    such as this <live-example name="architecture"></live-example> from the [Architecture](architecture.html) chapter.
+    such as this <live-example name="architecture"></live-example> from the [Architecture](architecture.html) page.
 
-    The link launches a browser-based code editor where we can inspect, modify, save, and download the code.
+    The link launches a browser-based code editor where you can inspect, modify, save, and download the code.
 
 :marked
-  A few early chapters are written as tutorials and are clearly marked as such.
+  A few early pages are written as tutorials and are clearly marked as such.
-  Most chapters are *not* tutorials.
+  The rest of the pages highlight key points in code rather than explain each step necessary to build the sample.
-  They highlight key points in code rather than explain each step necessary to build the sample.
+  You can always get the full source through the #{_liveLink}.
-  We can always get the full source by way of the #{_liveLink}.
 
   # Reference pages
 
@@ -120,10 +113,10 @@ block example-links
 
   # Feedback
 
-  We welcome feedback! Leave a comment by clicking the icon in upper right corner of the banner.
+  We welcome feedback! 
 
-  Post *documentation* issues and pull requests on the
+  Use the [angular.io Github repo](https://github.com/angular/angular.io) for **documentation** issues and pull requests.
-  [angular.io](https://github.com/angular/angular.io) github repository.
 
-  Post issues with *Angular 2 itself* to the [angular](https://github.com/angular/angular) github repository.
+
+  Use the [Angular Github repo](https://github.com/angular/angular) to report issues with **Angular 2** itself.
 // #enddocregion the-rest

public/docs/ts/latest/guide/ngmodule.jade

@@ -14,7 +14,7 @@ block includes
   It may add service providers to the application dependency injectors. 
   And there are more options covered here. 
 
-  This chapter explains how to **create** `NgModule` classes and how to load them, 
+  This page explains how to **create** `NgModule` classes and how to load them, 
   either immediately when the application launches or later, as needed, via the [Router](router.html).  
 
   ## Contents
@@ -34,7 +34,7 @@ block includes
   * [NgModule metadata properties](#ngmodule-properties "A technical summary of the @NgModule metadata properties")
 
   ### Live examples
-  This chapter explains Angular Modules through a progression of improvements to a sample with a "Tour of Heroes" theme.
+  This page explains Angular Modules through a progression of improvements to a sample with a "Tour of Heroes" theme.
   Here's an index to live examples at key moments in the evolution of that sample:
 
   * <live-example plnkr="minimal.0">A minimal NgModule app</live-example>
@@ -45,11 +45,11 @@ block includes
 
   ### Frequently Asked Questions (FAQs)
 
-  This chapter covers Angular Module concepts in a tutorial fashion.
+  This page covers Angular Module concepts in a tutorial fashion.
 
   The companion [Angular Module FAQs](../cookbook/ngmodule-faq.html "Angular Module FAQs") cookbook
   offers ready answers to specific design and implementation questions.
-  Read this chapter first before hopping over to those FAQs.
+  Read this page first before hopping over to those FAQs.
 
 .l-hr
 
@@ -92,7 +92,7 @@ a#angular-modularity
   that represent collections of related functionality. 
   We then import these modules into the _root module_.
 
-  We'll see how later in the chapter. Let's start with the _root module_.
+  We'll see how later in the page. Let's start with the _root module_.
 
 a#root_module 
 .l-main-section
@@ -131,7 +131,7 @@ a#bootstrap
   We launch the application by bootstrapping the `AppModule` in the `main.ts` file.
   
   Angular offers a variety of bootstrapping options, targeting multiple platforms. 
-  In this chapter we consider two options, both targeting the browser.
+  In this page we consider two options, both targeting the browser.
 
   ### Dynamic bootstrapping with the Just-In-Time (JIT) compiler
   In the first, _dynamic_ option, the [Angular compiler](../cookbook/ngmodule-faq.html#q-angular-compiler "About the Angular Compiler") 
@@ -139,7 +139,7 @@ a#bootstrap
 
 +makeExample('ngmodule/ts/app/main.ts', '', 'app/main.ts (dynamic)')(format=".")
 :marked
-  The samples in this chapter demonstrate the dynamic bootstrapping approach. 
+  The samples in this page demonstrate the dynamic bootstrapping approach. 
 
   <live-example embedded plnkr="minimal.0" img="devguide/ngmodule/minimal-plunker.png">Try the live example.</live-example>
   
@@ -219,7 +219,7 @@ a#providers
 
   Modules are a great way to provide services for all of the module's components.
 
-  The [Dependency Injection](dependency-injection.html) chapter describes
+  The [Dependency Injection](dependency-injection.html) page describes
   the Angular hierarchical dependency injection system and how to configure that system
   with [providers](dependency-injection.html#providers) at different levels of the
   application's component tree.
@@ -668,7 +668,7 @@ a#lazy-load
   ### App routing
 +makeExample('ngmodule/ts/app/app.routing.ts', '', 'app/app.routing.ts')(format='.')
 :marked
-  The router is the subject of [its own chapter](router.html) so we'll skip lightly over the details and 
+  The router is the subject of [its own page](router.html) so we'll skip lightly over the details and 
   concentrate on the intersection of Angular modules and routing.
 
   This file defines three routes. 
@@ -768,7 +768,7 @@ a#hero-module
     .file hero.service.ts
     .file highlight.directive.ts
 :marked
-  This is the child routing scenario familiar to readers of [Router](router.html#child-routing-component) chapter.
+  This is the child routing scenario familiar to readers of the [Router](router.html#child-routing-component) page.
   The `HeroComponent` is the feature's top component and routing host. 
   Its template has a `<router-outlet>` that displays either a list of heroes (`HeroList`) 
   or an editor of a selected hero (`HeroDetail`).
@@ -880,7 +880,7 @@ a#core-module
 .l-sub-section
   :marked
     We're importing some extra symbols from the Angular core library that we're not using yet.
-    They'll become relevant later in this chapter.
+    They'll become relevant later in this page.
 :marked
   The `@NgModule` metadata should be familiar. 
   We declare the `TitleComponent`  because this module _owns_ it and we export it

public/docs/ts/latest/guide/npm-packages.jade

@@ -1,20 +1,20 @@
 include ../_util-fns
 
 :marked
-  Angular applications and Angular itself depend upon features and functionality provided by a variety of third-party packages (including Angular itself).
+  Angular applications and Angular itself depend upon features and functionality provided by a variety of third-party packages.
   These packages are maintained and installed with the Node Package Manager (<a href="https://docs.npmjs.com/" target="_blank">npm</a>).
 .l-sub-section
   :marked
     Node.js and npm are essential to Angular 2 development. 
     
     <a href="https://docs.npmjs.com/getting-started/installing-node" target="_blank" title="Installing Node.js and updating npm">
-    Get it now</a> if it's not already installed on your machine.
+    Get them now</a> if they're not already installed on your machine.
  
-    **Verify that you are running at least node `v4.x.x` and npm `3.x.x`**
+    **Verify that you are running node `v4.x.x` or higher and npm `3.x.x` or higher**
-    by running `node -v` and `npm -v` in a terminal/console window.
+    by running the commands `node -v` and `npm -v` in a terminal/console window.
     Older versions produce errors.
 
-    We recommend [nvm](https://github.com/creationix/nvm) for managing multiple versions of node and npm.
+    We recommend [nvm](https://github.com/creationix/nvm) for managing multiple versions of node and npm. You may need [nvm](https://github.com/creationix/nvm) if you already have projects running on your machine that use other versions of node and npm.
 
 :marked
   We recommend a comprehensive starter-set of packages as specified in the `dependencies` and `devDependencies`
@@ -22,30 +22,27 @@ include ../_util-fns
   <a href="https://docs.npmjs.com/files/package.json" target="_blank">package.json</a> file:
 +makeJson('quickstart/ts/package.1.json',{ paths: 'dependencies, devDependencies'}, 'package.json (dependencies)')(format=".") 
 :marked
-  There are other possible package choices and you're likely to add and subtract to meet your application needs. 
+  You can use other packages but we recommend *this particular set* to start with because (a) they  work well together and 
-  We're recommending *this particular set* because (a) we know they  work well together and 
+  (b) they include everything you'll need to build and run the sample applications in this series.
-  (b) they include everything we'll need to build and run the sample applications in this documentation series.
 .l-sub-section
   :marked
-    *Almost* everything. A cookbook or guide chapter may require an additional library such as *jQuery*.
+    Note: A cookbook or guide page may require an additional library such as *jQuery*.
 :marked
-  This is far more than we need for QuickStart. 
+  You'll install more than you need for QuickStart. 
-  Indeed, it's more than we need for most applications. 
+  No worries! 
-  There is no harm in installing more than we need. 
+  You only serve to the client those packages that the application actually requests.
-  We only serve to the client those packages that the application actually requests.
   
-  In this chapter we explain what each package does and why we include it.
+  This page explains what each package does. You can make substitutions later to suit your tastes and experience.
-  Feel free to make substitutions later to suit your tastes and experience.
   
 .l-main-section
 :marked
   ## *dependencies* and *devDependencies*
-  The `package.json` distinguishes between two sets of packages, 
+  The `package.json` includes two sets of packages, 
   [dependencies](#dependencies) and [devDependencies](#dev-dependencies).
   
-  The packages listed under *dependencies* are essential to *running* the application. 
+  The *dependencies* are essential to *running* the application. 
   The *devDependencies* are only necessary to *develop* the application. 
-  They can be excluded from production installations as in this example:
+  You can exclude them from production installations by adding `--production` to the install command, as follows:
 code-example(format="." language="bash").
   npm install my-application --production
   
@@ -53,9 +50,9 @@ a(id="dependencies")
 .l-main-section
 :marked
   ## *dependencies*
-  There are three package categories in the `dependencies` section of the application `package.json`:
+  The `dependencies` section of `package.json` contains:
   
-  * ***Features*** - Feature packages provide our application with framework and utility capabilities.
+  * ***Features*** - Feature packages give the application framework and utility capabilities.
   
   * ***Polyfills*** - Polyfills plug gaps in the browser's JavaScript implementation.
  
@@ -68,19 +65,18 @@ a(id="dependencies")
   ***@angular/core*** - Critical runtime parts of the framework needed by every application. 
   Includes all metadata decorators, `Component`, `Directive`,  dependency injection, and the component lifecycle hooks.
   
-  ***@angular/common*** - The commonly needed services, pipes and directives provided by the Angular team.
+  ***@angular/common*** - The commonly needed services, pipes, and directives provided by the Angular team.
   
   ***@angular/compiler*** - Angular's *Template Compiler*. 
-  It understand templates and can convert them to code that makes the app run and render. 
+  It understands templates and can convert them to code that makes the application run and render. 
-  Developers typically don’t interact with the compiler directly. 
+  Typically you don’t interact with the compiler directly; rather, you use it indirectly via `platform-browser-dynamic` or the offline template compiler.
-  They use it indirectly via `platform-browser-dynamic` or the offline template compiler.
   
   ***@angular/platform-browser*** - Everything DOM and browser related, especially the pieces that help render into DOM.
   This package also includes the bootstrapStatic method for bootstrapping applications for production builds that pre-compile templates offline.
   
-  ***@angular/platform-browser-dynamic*** - Providers and a bootstrap method for applications that
+  ***@angular/platform-browser-dynamic*** - Includes [Providers](https://angular.io/docs/ts/latest/api/core/index/Provider-type-alias.html) and a [bootstrap](https://angular.io/docs/ts/latest/guide/ngmodule.html#!#bootstrap) method for applications that
   compile templates on the client. Don’t use offline compilation.
-  We use this package for boostrapping during development and for boostrapping plunker samples.
+  Use this package for bootstrapping during development and for bootstrapping plunker samples.
   
   ***@angular/http*** - Angular's http client.
   
@@ -90,43 +86,42 @@ a(id="dependencies")
   
   ***[system.js](https://github.com/systemjs/systemjs)*** -  A dynamic module loader compatible with the 
   [ES2015 module](http://www.2ality.com/2014/09/es6-modules-final.html) specification.
-  There are other viable choices including the well-regarded [webpack](https://webpack.github.io/).
+  Other viable choices include the well-regarded [webpack](https://webpack.github.io/).
-  SystemJS happens to be the one we use in the documentation samples. It works.
   
-  Our applications are likely to require additional packages that provide
+  Your future applications are likely to require additional packages that provide
   HTML controls, themes, data access, and various utilities.
   
 
 a(id="polyfills")
 .l-main-section
 :marked
-  ### Polyfill Packages
+  ### Polyfill packages
   
   Angular requires certain [polyfills](https://en.wikipedia.org/wiki/Polyfill) in the application environment.
-  We install these polyfills with very specific npm packages that Angular lists in the *peerDependencies* section of its `package.json`.
+  Install these polyfills using the npm packages that Angular lists in the *peerDependencies* section of its `package.json`.
   
-  We must list these packages in the `dependencies` section of our own `package.json`.
+  You must list these packages in the `dependencies` section of your own `package.json`.
   
 .l-sub-section
   :marked
-    See "[Why peerDependencies?](#why-peer-dependencies)" below for background on this requirement.
+    For background on this requirement, see [Why peerDependencies?](#why-peer-dependencies).
 :marked
-  ***core-js*** - Monkey patches the global context (window) with essential features of ES2015 (ES6).
+  ***core-js*** - Patches the global context (window) with essential features of ES2015 (ES6).
-   Developers may substitute an alternative polyfill that provides the same core APIs. 
+   You may substitute an alternative polyfill that provides the same core APIs. 
-   This dependency should go away once these APIs are implemented by all supported ever-green browsers.
+   When these APIs are implemented by the major browsers, this dependency will become unnecessary.
 
   ***reflect-metadata*** - A dependency shared between Angular and the ***TypeScript compiler***. 
-  Developers should be able to update a TypeScript package without upgrading Angular, 
+  You can update a TypeScript package without upgrading Angular, 
   which is why this is a dependency of the application and not a dependency of Angular.
   
   ***rxjs*** - A polyfill for the [Observables specification](https://github.com/zenparsing/es-observable) currently before the 
   [TC39](http://www.ecma-international.org/memento/TC39.htm) committee that determines standards for the JavaScript language.
-  Developers should be able to pick a preferred version of *rxjs* (within a compatible version range) 
+  You can pick a preferred version of *rxjs* (within a compatible version range) 
   without waiting for Angular updates.
   
   ***zone.js*** - A polyfill for the [Zone specification](https://gist.github.com/mhevery/63fdcdf7c65886051d55) currently before the 
   [TC39](http://www.ecma-international.org/memento/TC39.htm) committee that determines standards for the JavaScript language.
-  Developers should be able to pick a preferred version of *zone.js* to use (within a compatible version range) 
+  You can pick a preferred version of *zone.js* to use (within a compatible version range) 
   without waiting for Angular updates.
 
 a(id="other")
@@ -136,99 +131,94 @@ a(id="other")
   
   ***angular2-in-memory-web-api*** - An Angular-supported library that simulates a remote server's web api 
   without requiring an actual server or real http calls. 
-  Good for demos, documentation samples, and early stage development (before we even have a server).
+  Good for demos, samples, and early stage development (before we even have a server).
-  Learn about it in the [Http Client](server-communication.html#appendix-tour-of-heroes-in-memory-server) chapter.
+  Read about it in the [Http Client](server-communication.html#appendix-tour-of-heroes-in-memory-server) page.
   
   ***bootstrap*** - [Bootstrap](http://getbootstrap.com/) is a popular HTML and CSS framework for designing responsive web apps.
-  Some of the documentation samples improve their appearance with *bootstrap*.
+  Some of the samples improve their appearance with *bootstrap*.
   
 a(id="dev-dependencies")
 .l-main-section
 :marked
   ## *devDependencies*
-  The packages listed in the *devDependencies* section of the `package.json` help us develop the application.
+  The packages listed in the *devDependencies* section of the `package.json` help you develop the application.
-  They do not have to be deployed with the production application although there is rarely harm in doing so.
+  You don't have to deploy them with the production application although there is no harm in doing so.
 
   ***[concurrently](https://www.npmjs.com/package/concurrently)*** - 
   A utility to run multiple *npm* commands concurrently on OS/X, Windows, and Linux operating systems.
   
   ***[lite-server](https://www.npmjs.com/package/lite-server)*** - 
-  A light-weight, static file server, written and maintained by [John Papa](http://johnpapa.net/) 
+  A light-weight, static file server, by [John Papa](http://johnpapa.net/) 
   with excellent support for Angular apps that use routing.
   
   ***[typescript](https://www.npmjs.com/package/typescript)*** - 
-  The TypeScript language server including the *tsc* TypeScript compiler.
+  The TypeScript language server, including the *tsc* TypeScript compiler.
   
   ***[typings](https://www.npmjs.com/package/typings)*** - A manager for TypeScript definition files.
-  Learn more about it in the [TypeScript Configuration](typescript-configuration.html#typings) chapter.
+  Read more about it in the [TypeScript Configuration](typescript-configuration.html#typings) page.
-  
-  This section likely grows as we add more tools, testing, and build support. 
-  The QuickStart set is sufficient for developing the documentation sample applications.
 
 .l-main-section
 a(id="why-peer-dependencies")
 :marked
   ## Why *peerDependencies*?
   
-  We don't have a *peerDependencies* section in the QuickStart `package.json`. 
+  There isn't a *peerDependencies* section in the QuickStart `package.json`. 
-  But Angular itself has a *peerDependencies* section in 
+  But Angular has a *peerDependencies* section in 
-  *its* package.json and that has important consequences for our application. 
+  *its* package.json, which has important consequences for your application. 
   
-  It explains why we load the [polyfill](#polyfills) *dependency* packages in the QuickStart `package.json`,
+  It explains why you load the [polyfill](#polyfills) *dependency* packages in the QuickStart `package.json`,
-  and why we'll need those packages in our own applications.
+  and why you'll need those packages in your own applications.
   
-  Let's briefly explain what [peer dependencies](https://nodejs.org/en/blog/npm/peer-dependencies/) are about.
+  An explanation of [peer dependencies](https://nodejs.org/en/blog/npm/peer-dependencies/) follows.
   
-  As we know, packages depend on other packages. For example, our application depends upon the Angular package.
+  Packages depend on other packages. For example, your application depends on the Angular package.
   
-  Two packages, 'A' and 'B', could depend on the same third package 'C'. 
+  Two packages, "A" and "B", could depend on the same third package "C". 
-  'A' and 'B' might both list 'C' among their *dependencies*.
+  "A" and "B" might both list "C" among their *dependencies*.
   
-  What if 'A' and 'B' depend on different versions of 'C' ('C1' and 'C2'). The npm package system supports that! 
+  What if "A" and "B" depend on different versions of "C" ("C1" and "C2"). The npm package system supports that. 
-  It installs 'C1' in the `node_modules` folder for 'A' and 'C2' in the `node_modules` folder for 'B'.
+  It installs "C1" in the `node_modules` folder for "A" and "C2" in the `node_modules` folder for "B".
-  Now 'A' and 'B' have their own copies of 'C' and they run without interferring. This is great.
+  Now "A" and "B" have their own copies of "C" and they run without interferring with one another.
   
-  But there is a problem. Package 'A' may require the presence of 'C1' without actually calling upon it directly.
+  But there is a problem. Package "A" may require the presence of "C1" without actually calling upon it directly.
-  'A' may only work if *everyone is using 'C1'*. It falls down if any part of the application relies on 'C2'.
+  "A" may only work if *everyone is using "C1"*. It falls down if any part of the application relies on "C2".
   
-  The solution is for 'A' to declare that 'C1' is a *peer dependency*.
+  The solution is for "A" to declare that "C1" is a *peer dependency*.
   
   The difference between a `dependency` and a `peerDependency` is roughly this:
   
   >A **dependency** says, "I need this thing directly available to *me*."
   >
-  >A **peerDependency** says, "if you want to use me, you need this thing available to *you*."
+  >A **peerDependency** says, "If you want to use me, you need this thing available to *you*."
    
-  Angular finds itself in this situation. 
+  The Angular `package.json` specifies several *peer dependency* packages, 
-  Accordingly, the Angular `package.json` specifies several *peer dependency* packages, 
   each pinned to a particular version of a third-party package.
 
-  ### We must install Angular's *peerDependencies* ourselves
+  ### We must install Angular's *peerDependencies* ourselves.
   
-  When *npm* installs packages listed in *our* `dependencies` section,
+  When *npm* installs packages listed in *your* `dependencies` section,
   it also installs the packages listed within *their* packages `dependencies` sections.
   The process is recursive.
   
-  But as of version 3, *npm* does *not* install packages listed in *peerDependencies* sections.
+  However, as of version 3, *npm* does *not* install packages listed in *peerDependencies* sections.
   
-  That means when our application installs Angular, ***npm* will not automatically install
+  This means that when your application installs Angular, ***npm* doesn't automatically install
   the packages listed in Angular's *peerDependencies* section**.
   
-  Fortunately, *npm* warns us (a) when any *peer dependencies* are missing or (b)
+  Fortunately, *npm* issues a warning (a) When any *peer dependencies* are missing, or (b)
-  when the application or any its other dependencies
+  When the application or any of its other dependencies
   installs a different version of a *peer dependency*. 
   
-  These warnings are a critical guard against accidental failures due to version mismatches.
+  These warnings guard against accidental failures due to version mismatches.
-  They leave us in control of package and version resolution.
+  They leave you in control of package and version resolution.
   
-  It is our responsibility to list all *peer dependency* packages **among our own *devDependencies***.
+  It is your responsibility to list all *peer dependency* packages **among your own *devDependencies***.
   
 .l-sub-section
   :marked
     #### The future of *peerDependencies*
     
-    The Angular polyfill dependencies should be just a suggestion or a hint to developers so that they know what Angular expects.
+    The Angular polyfill dependencies are hard requirements. Currently, there is no way to make them optional.
-    They should not be hard requirements as they are today. We don't have a way to make them optional today.
     
-    There is a npm feature request for "optional peerDependencies" which would allow us to model this relationship better. 
+    However, there is an npm feature request for "optional peerDependencies," which would allow you to model this relationship better. 
-    Once implemented, Angular will switch from *peerDependencies* to *optionalPeerDependencies* for all polyfills.
+    When this feature request is implemented, Angular will switch from *peerDependencies* to *optionalPeerDependencies* for all polyfills.

public/docs/ts/latest/guide/typescript-configuration.jade

@@ -1,15 +1,13 @@
 include ../_util-fns
 
 :marked
-  TypeScript is a primary language for Angular application development.
+  TypeScript is a primary language for Angular application development. It is a dialect of JavaScript with design-time support for type-safety and tooling.
   
-  TypeScript is a dialect of JavaScript with design-time support for type-safety and tooling.
+  Browsers can't execute TypeScript directly. Typescript must be "transpiled" into JavaScript using the *tsc* compiler,
+  which requires some configuration.
   
-  Browsers can't execute TypeScript directly. It has to be "transpiled" into JavaScript with the *tsc* compiler
+  This page covers some aspects of TypeScript configuration and the TypeScript environment
-  and that effort requires some configuration.
+  that are important to Angular developers, including details about the following files:
-  
-  This chapter covers some aspects of TypeScript configuration and the TypeScript environment
-  that are important to Angular developers.
   
   * [tsconfig.json](#tsconfig) - TypeScript compiler configuration.
   * [typings](#typings) - TypesScript declaration files.
@@ -18,44 +16,41 @@ a(id="tsconfig")
 .l-main-section
 :marked
   ## *tsconfig.json*
-  We typically add a TypeScript configuration file (`tsconfig.json`) to our project to
+  Typically, you add a TypeScript configuration file (`tsconfig.json`) to your project to
   guide the compiler as it generates JavaScript files.
 .l-sub-section
   :marked
-    Get details about `tsconfig.json` from the official
+    For details about `tsconfig.json`, see the official
     [TypeScript wiki](http://www.typescriptlang.org/docs/handbook/tsconfig-json.html).
 :marked
-  We created the following `tsconfig.json` for the [QuickStart](../quickstart.html):
+  We created the following `tsconfig.json` for [QuickStart](../quickstart.html):
 +makeJson('quickstart/ts/tsconfig.1.json', null, 'tsconfig.json')(format=".")
 :marked
-  The options and flags in this file are essential for Angular 2 applications.
+  This file contains options and flags that are essential for Angular 2 applications.
   
   <a id="noImplicitAny"></a>
   ### *noImplicitAny* and *suppressImplicitAnyIndexErrors*
 
   TypeScript developers disagree about whether the `noImplicitAny` flag should be `true` or `false`.
-  There is no correct answer and we can change the flag later.
+  There is no correct answer and you can change the flag later.
-  But our choice now can make a difference in larger projects so it merits discussion.
+  But your choice now can make a difference in larger projects, so it merits discussion.
 
-  When the `noImplicitAny` flag is `false` (the default),
+  When the `noImplicitAny` flag is `false` (the default), and if
-  the compiler silently defaults the type of a variable to `any` if it cannot infer
+  the compiler cannot infer the variable type based on how it's used, the compiler silently defaults the type to `any`. That's what is meant by *implicit `any`*.
-  the type based on how the variable is used. That's what we mean by *implicit `any`*.
 
-  We initialized the `noImplicitAny` flag to `false` in the QuickStart 
+  In the QuickStart exercise, the `noImplicitAny` flag is initialized to `false`
   to make learning TypeScript development easier.
   
   When the `noImplicitAny` flag is `true` and the TypeScript compiler cannot infer
-  the type, it still generates the JavaScript files. But it also **reports an error**.
+  the type, it still generates the JavaScript files, but it also **reports an error**.
   Many seasoned developers prefer this stricter setting because type checking catches more
   unintentional errors at compile time.
   
-  We can set a variable's type to `any` even when the `noImplicitAny` flag is `true`.
+  You can set a variable's type to `any` even when the `noImplicitAny` flag is `true`.
-  We do so when that seems like the best choice for the situation, 
-  deliberately and explicitly, after giving the matter some thought.
 
-  If we set the `noImplicitAny` flag to `true`, we may get *implicit index errors* as well.
+  If you set the `noImplicitAny` flag to `true`, you may get *implicit index errors* as well.
   Most developers feel that *this particular error* is more annoying than helpful.
-  We can suppress them with the following additional flag.
+  You can suppress them with the following additional flag:
 code-example(format=".").
   "suppressImplicitAnyIndexErrors":true
 
@@ -64,68 +59,64 @@ a(id="typings")
 .l-main-section
 :marked
   ## TypeScript Typings
-  Many JavaScript libraries such as jQuery, the Jasmine testing library, and Angular itself,
+  Many JavaScript libraries, such as jQuery, the Jasmine testing library, and Angular,
   extend the JavaScript environment with features and syntax
   that the TypeScript compiler doesn't recognize natively.
   When the compiler doesn't recognize something, it throws an error. 
   
-  We use [TypeScript type definition files](http://www.typescriptlang.org/Handbook#writing-dts-files)
+  Use [TypeScript type definition files](http://www.typescriptlang.org/Handbook#writing-dts-files)&mdash;`d.ts files`&mdash;to tell the compiler about the libraries you load.
-  &mdash; *d.ts files* &mdash; to tell the compiler about the libraries we load.
   
   TypeScript-aware editors leverage these same definition files to display type information about library features.
   
-  Many libraries include their definition files in their npm packages where both the TypeScript compiler and editors
+  Many libraries include definition files in their npm packages where both the TypeScript compiler and editors
   can find them. Angular is one such library. 
-  Peek into the `node_modules/@angular/core/` folder of any Angular application to see several `...d.ts` files that describe parts of Angular.
+  The `node_modules/@angular/core/` folder of any Angular application contains several `d.ts` files that describe parts of Angular.
   
-  **We need do nothing to get *typings* files for library packages which include *d.ts* files &mdash; as all Angular packages do.**
+  **You need do nothing to get *typings* files for library packages that include `d.ts` files&mdash;as all Angular packages do.**
   
   ### Installable typings files
-  Sadly, many libraries &mdash; jQuery, Jasmine, and Lodash among them &mdash; do *not* include `d.ts` files in their npm packages.
+  Many libraries&mdash;jQuery, Jasmine, and Lodash among them&mdash;do *not* include `d.ts` files in their npm packages.
-  Fortunately, either their authors or community contributors have created separate *d.ts* files for these libraries and 
+  Fortunately, either their authors or community contributors have created separate `d.ts` files for these libraries and 
   published them in well-known locations.
-  The *typings* tool can find and fetch these files for us.
+  The *typings* tool can find and fetch these files for you.
   
-  We installed the [typings](https://github.com/typings/typings/blob/master/README.md) tool 
+  After installing the [typings](https://github.com/typings/typings/blob/master/README.md) tool 
-  with npm (it's listed among the *devDependencies* in the `package.json`) and added an npm script
+  with npm (it's listed among the *devDependencies* in the `package.json`), add an npm script (`postinstall`)
-  to run that tool automatically after *npm* installation completes.
+  to run that tool automatically, after *npm* installation finishes.
 +makeJson('quickstart/ts/package.1.json', {paths: 'scripts.postinstall'}, 'package.json (postinstall)')(format=".")
 :marked
-  This *typings* tool command installs the *d.ts* files that we identify in a `typings.json` file into the **typings** folder.
+  This *typings* tool command, `typings install`, installs the `d.ts` files into the **typings** folder.
-  We created a `typings.json` file in the [QuickStart](../quickstart.html):
+  You created a `typings.json` file in the [QuickStart](../quickstart.html):
 +makeJson('quickstart/ts/typings.1.json', null, 'typings.json')(format=".")
 :marked
-  We identified three *typings* file in the QuickStart, the *d.ts* files for
+  QuickStart identified three *typings* (`d.ts`) files:
   
   * [core-js](https://github.com/zloirock/core-js/blob/master/README.md)
-  that brings ES2015/ES6 capabilities to our ES5 browsers
+  brings ES2015/ES6 capabilities to ES5 browsers
   
   * [jasmine](http://jasmine.github.io/) typings for the Jasmine test framework
   
-  * [node](https://github.com/DefinitelyTyped/DefinitelyTyped/blob/master/node/node.d.ts) for code that references objects in the nodejs environment; 
+  * [node](https://github.com/DefinitelyTyped/DefinitelyTyped/blob/master/node/node.d.ts) for code that references objects in the *nodejs* environment; 
-  see the [webpack](./webpack.html) chapter for an example.
+  You can view an example in the [webpack](./webpack.html) page.
   
-  QuickStart itself doesn't require these typings but many of the documentation samples do.
+  QuickStart doesn't require these typings but many of the samples do.
-  Most of us would be disappointed if we couldn't code against 
-  typical ES2015 features or support testing right out-of-the-box.
 
-  We can also run the *typings* tool ourselves.
+  You can also run the *typings* tool yourself.
-  The following command (re)installs the typings files, as is sometimes necessary when the `postInstall` hook fails to do so.
+  If the `postInstall` command fails to (re)install the typings files, run the following command to do so.
 code-example(format="").
   npm run typings install
 :marked
-  This command lists the installed typings files:
+  Run this command to list the installed typings files:
 code-example(format="").
   npm run typings list
 :marked
-  The following command installs or updates the typings file for the Jasmine test library from the *DefinitelyTyped* repository
+  The following command installs or updates the typings file for the Jasmine test library from the *DefinitelyTyped* repository,
-  and updates the `typings.config` so we that we get it automatically the next time we install typings.
+  and updates the `typings.config` file so you receive it automatically the next time you install typings.
 code-example(format="").
   npm run typings -- install dt~jasmine --save --global
 .l-sub-section
   :marked
-    The [&ndash;&ndash; option](https://docs.npmjs.com/cli/run-script) is important; 
+    The [&ndash;&ndash; option](https://docs.npmjs.com/cli/run-script) tells npm to pass all arguments to the right of `--` to the *typings* command.
-    it tells npm to pass all arguments to the right of `--` to the *typings* command.
     
-    Learn about the features of the *typings* tool at its [site on github](https://github.com/typings/typings/blob/master/README.md).
+    Read about the features of the *typings* tool at its [site on github](https://github.com/typings/typings/blob/master/README.md).
 

public/features.jade

@@ -3,8 +3,8 @@ div
     h2(class="text-headline") Cross Platform
     div(class="feature-row")
       div(class="feature")
-        h3 Progressive Web Apps
+        h3 Progressive web apps
-        p(class="text-body") Use modern web platform capabilities to deliver app-like experiences.  High performance, offline and zero-step installation.
+        p(class="text-body") Use modern web platform capabilities to deliver app-like experiences.  High performance, offline, and zero-step installation.
 
       div(class="feature")
         h3 Native
@@ -12,19 +12,19 @@ div
 
       div(class="feature")
         h3 Desktop
-        p(class="text-body") Create desktop-installed apps across Mac, Windows, and Linux using the same Angular methods you've learned for the web plus ability to access native OS APIs.
+        p(class="text-body") Create desktop-installed apps across Mac, Windows, and Linux using the same Angular methods you've learned for the web plus the ability to access native OS APIs.
 
-    h2(class="text-headline") Speed & Performance
+    h2(class="text-headline") Speed and Performance
     div(class="feature-row")
       div(class="feature")
         h3 Code generation
-        p(class="text-body") Angular turns your templates into code that's highly optimized for today's JavaScript virtual machines giving you all the benefits of hand-written code with the productivity of a framework.
+        p(class="text-body") Angular turns your templates into code that's highly optimized for today's JavaScript virtual machines, giving you all the benefits of hand-written code with the productivity of a framework.
       div(class="feature")
         h3 Universal
-        p(class="text-body") Serve the first view of your application on node.js, .NET, PHP and other servers for near-instant rendering in just HTML and CSS.  Also paves the way for sites that optimize for SEO.
+        p(class="text-body") Serve the first view of your application on node.js, .NET, PHP, and other servers for near-instant rendering in just HTML and CSS.  Also paves the way for sites that optimize for SEO.
       div(class="feature")
-        h3 Code Splitting
+        h3 Code splitting
-        p(class="text-body") Angular apps load quickly with the new Component Router that delivers automatic code-splitting so users only load code required to render the view they request.
+        p(class="text-body") Angular apps load quickly with the new Component Router, which delivers automatic code-splitting so users only load code required to render the view they request.
 
     h2(class="text-headline") Productivity
     div(class="feature-row")
@@ -36,16 +36,16 @@ div
         p(class="text-body") Command line tools: start building fast, add components and tests, then instantly deploy.
       div(class="feature")
         h3 IDEs
-        p(class="text-body") Get intelligent code completion, instant errors and other feedback in popular editors and IDEs.
+        p(class="text-body") Get intelligent code completion, instant errors, and other feedback in popular editors and IDEs.
 
     h2(class="text-headline") Full Development Story
     div(class="feature-row")
       div(class="feature")
         h3 Testing
-        p(class="text-body") With Karma for unit tests, you can know if you've broken things every time you save. And Protractor makes your scenario tests run faster and stably.
+        p(class="text-body") With Karma for unit tests, you can know if you've broken things every time you save. And Protractor makes your scenario tests run faster and in a stable manner.
       div(class="feature")
         h3 Animation
-        p(class="text-body") Create high performance complex choreographies and animation timelines with very little code through Angular's intuitive API.
+        p(class="text-body") Create high-performance, complex choreographies and animation timelines with very little code through Angular's intuitive API.
       div(class="feature")
         h3 Accessibility
         p(class="text-body") Create accessible applications with ARIA-enabled components, developer guides, and built-in a11y test infrastructure.