docs(quickstart): edit Dart & TS QuickStarts

closes #1411

public/docs/dart/latest/quickstart.jade

@@ -13,8 +13,7 @@ block setup-tooling
   :marked
     Install the **[Dart SDK](https://www.dartlang.org/downloads/)**,
     if not already on your machine, and any tools you like to use with Dart.
-    The Dart SDK includes **[pub][pub]**, the Dart package manager, that we
+    The Dart SDK includes tools such as **[pub][pub]**, the Dart package manager.
-    will be using shortly.
     If you don't have a favorite Dart editor already, try
     [WebStorm][WS], which comes with a Dart plugin.
     You can also download [Dart plugins for other IDEs and editors][DT].
@@ -28,15 +27,17 @@ block download-source
 
 block package-and-config-files
   :marked
-    In the project folder just created, put a file named
+    In the project folder just created, create a file named
-    **[pubspec.yaml][pubspec]** in it.
+    **[pubspec.yaml][pubspec]** with the code below.
-    As shown below, in `pubspec.yaml`, specify the angular2 and browser
+    This pubspec must specify the **angular2** and **browser**
-    packages as dependencies, as well as the angular2 transformer.
+    packages as dependencies, as well as the `angular2` transformer.
+    It can also specify other packages and transformers for the app to use,
+    such as [dart_to_js_script_rewriter](https://pub.dartlang.org/packages/dart_to_js_script_rewriter).
     Angular 2 is still changing, so provide an exact version: **2.0.0-beta.17**.
 
     [pubspec]: https://www.dartlang.org/tools/pub/pubspec.html
 
-  +makeExample('quickstart/dart/pubspec.yaml', 'no-rewriter', 'pubspec.yaml')
+  +makeExample('quickstart/dart/pubspec.yaml', null, 'pubspec.yaml')
 
 block install-packages
   :marked
@@ -57,35 +58,34 @@ block create-main
     Now we need something to tell Angular to load the root component.
     Create:
   ul
-    li a #[b folder named #[code web]], and inside it
+    li a #[b folder named #[code web]]
-    li the file #[code #[+adjExPath('app/main.ts')]] with the following content:
+    li a <b>file named #[code #[+adjExPath('app/main.ts')]]</b> with the following content:
 
 block index-html-commentary-for-ts
   //- N/A
 
 block run-app
   p.
-    You have a few options for running your app.
+    We have a few options for running our app.
     One is to launch a local HTTP server
     and then view the app in
     <a href="https://www.dartlang.org/tools/dartium/">Dartium</a>.
-    You can use whatever server you like, such as WebStorm's server
+    We can use any web server, such as WebStorm's server
     or Python's SimpleHTTPServer.
   p.
     Another option is to build and serve the app using <code>pub serve</code>,
     and then run it by visiting <b><code>http://localhost:8080</code></b> in any modern browser.
     Pub serve generates JavaScript on the fly,
-    which can take a while when you first visit the page.
+    which can take a while when first visiting the page.
-    Pub serve also runs in <b><i>watch mode</i></b>, and will re-compile and subsequently serve
+    Pub serve also runs in <b><i>watch mode</i></b>, and will recompile and subsequently serve
-    and changed assets.
+    any changed assets.
   p.
-    Once the app is running, you should see the following in your browser
+    Once the app is running, the browser window should show the following:
-    window:
 
 block build-app
   .alert.is-important
     :marked
-      If you don't see that, make sure you've entered all the code correctly,
+      If you don't see **My First Angular 2 App**, make sure you've entered all the code correctly,
       in the [proper folders](#wrap-up),
       and run `pub get`.
 
@@ -93,21 +93,8 @@ block build-app
     h3#section-angular-run-app Building the app (generating JavaScript)
 
     :marked
-      Before you can deploy your app, you need to generate JavaScript files.
+      Before deploying the app, we need to generate JavaScript files.
       The `pub build` command makes that easy.
-      To improve your app's performance, convert the
-      HTML file to directly include the generated JavaScript;
-      one way to do that is with `dart_to_js_script_rewriter`.
-
-      Add the `dart_to_js_script_rewriter` package to your pubspec,
-      in both the `dependencies` and `transformers` sections.
-
-    - var stylePattern = { pnk: /(dart_to_js_script_rewriter.*$)|(- dart_to_js_script_rewriter.*$)/gm, otl: /(dependencies:)|(transformers:)/g };
-    +makeExample('quickstart/dart/pubspec.yaml', null, 'pubspec.yaml', stylePattern)
-
-    p.
-      Then compile your Dart code to JavaScript,
-      using <code>pub build</code>.
 
     code-example(language="sh").
       &gt; <span class="blk">pub build</span>
@@ -115,11 +102,14 @@ block build-app
 
     p.
       The generated JavaScript appears, along with supporting files,
-      under the <code>build</code> directory.
+      under a directory named <code>build</code>.
+
+    h4#angular_transformer Using the Angular transformer
+
     p.
-      When you generate JavaScript for an Angular app,
+      When generating JavaScript for an Angular app,
       be sure to use the Angular transformer.
-      It analyzes your code,
+      It analyzes the Dart code,
       converting reflection-using code to static code
       that Dart's build tools can compile to faster, smaller JavaScript.
       The highlighted lines in <code>pubspec.yaml</code>
@@ -130,7 +120,7 @@ block build-app
 
     p.
       The <code>entry_points</code> item
-      identifies the Dart file in your app
+      identifies the Dart file in our app
       that has a <code>main()</code> function.
       For more information, see the
       <a href="https://github.com/angular/angular/wiki/Angular-2-Dart-Transformer">Angular
@@ -139,29 +129,48 @@ block build-app
     #performance.l-sub-section
       h3 Performance, the transformer, and Angular 2 libraries
       p.
-        When you import <code>bootstrap.dart</code>,
+        When an app imports <code>bootstrap.dart</code>,
-        you also get <code>dart:mirrors</code>,
+        it also gets <code>dart:mirrors</code>,
         a reflection library that
         causes performance problems when compiled to JavaScript.
         Don't worry,
-        the Angular transformer converts your entry points
+        the Angular transformer converts the app's entry points
         (<code>entry_points</code> in <code>pubspec.yaml</code>)
         so that they don't use mirrors.
 
+    h4#dart_to_js_script_rewriter Using dart_to_js_script_rewriter
+
+    :marked
+      To improve the app's performance, convert the
+      HTML file to directly include the generated JavaScript;
+      one way to do that is with `dart_to_js_script_rewriter`.
+      To use the rewriter, specify `dart_to_js_script_rewriter` in both
+      the `dependencies` and `transformers` sections of the pubspec.
+
+    - var stylePattern = { otl: /(dart_to_js_script_rewriter.*$)|(- dart_to_js_script_rewriter.*$)|(dependencies:)|(transformers:)/gm };
+    +makeExample('quickstart/dart/pubspec.yaml', null, 'pubspec.yaml', stylePattern)
+
+    .alert.is-important
+      :marked
+        The `dart_to_js_script_rewriter` transformer must be
+        **after** the `angular2` transformer in `pubspec.yaml`.
+
+    :marked
+      For more information, see the docs for
+      [dart_to_js_script_rewriter](https://pub.dartlang.org/packages/dart_to_js_script_rewriter).
+
 block server-watching
   :marked
-    Pub serve is watching and 
+    To see the new version, just reload the page.
-    should detect the change, recompile the Dart into JavaScript,
-    refresh the browser, and display the revised message.
-    It's a nifty way to develop an application!
 
-    Ensure that you terminate the `pub serve` process once you are done.
+  .alert.is-important
+    :marked
+      Be sure to terminate the `pub serve` process once you stop working on this app.
 
 block project-file-structure
   .filetree
     .file angular2-quickstart
     .children
-      .file build ...
       .file lib
       .children
         .file app_component.dart
@@ -169,9 +178,20 @@ block project-file-structure
       .file web
       .children
         .file index.html
-        .file main.ts
+        .file main.dart
         .file styles.css
 
+  .l-verbose-section
+    :marked
+      This figure doesn't show generated files and directories.
+      For example, a `pubspec.lock` file
+      specifies versions and other identifying information for
+      the packages that our app depends on.
+      The `pub build` command creates a `build` directory
+      containing the JavaScript version of our app.
+      Pub, IDEs, and other tools often create
+      other directories and dotfiles.
+
 block project-files
   +makeTabs(`
       quickstart/ts/app/app.component.ts,

public/docs/ts/latest/quickstart.jade

@@ -32,13 +32,13 @@ figure.image-display
 
 h1 Build this app!
 :marked
-  - [Prerequisite](#prereq): install #{_prereq}
+  - [Prerequisite](#prereq): Install #{_prereq}
-  - [Step 1](#create-and-configure): create the app’s project folder and
+  - [Step 1](#create-and-configure): Create the app’s project folder and
     define package dependencies and special project setup
-  - [Step 2](#root-component): create the app’s Angular root component
+  - [Step 2](#root-component): Create the app’s Angular root component
-  - [Step 3](#main): add `main.#{_docsFor}`, identifying the root component to Angular
+  - [Step 3](#main): Add `main.#{_docsFor}`, identifying the root component to Angular
-  - [Step 4](#index): add `index.html`, the web page that hosts the application
+  - [Step 4](#index): Add `index.html`, the web page that hosts the application
-  - [Step 5](#build-and-run): build and run the app
+  - [Step 5](#build-and-run): Build and run the app
   - [Make some changes to the app](#make-some-changes)
   - [Wrap up](#wrap-up)
 
@@ -70,7 +70,7 @@ button(class="verbose on md-primary md-button md-ink-ripple", type="button", onc
     Explanations have a thin border on the left like *this* block of text.
 
     Click *Hide Explanations* to show only the instructions.
-    Click it again to see everything again.
+    Click *View Explanations* to see everything again.
 
 .l-sub-section
   :marked
@@ -79,15 +79,15 @@ button(class="verbose on md-primary md-button md-ink-ripple", type="button", onc
     Click the glyph on the right to copy code snippets to the clipboard  ==>
 
 .l-main-section
-h2#create-and-configure Step 1: create and configure the project
+h2#create-and-configure Step 1: Create and configure the project
 
 - var _package_and_config_files = _docsFor == 'dart' ? 'pubspec.yaml' : 'package definition and configuration files'
 
 :marked
   In this step we:
-  * [(a) Create the project folder](#create-the-project-folder).
+  * [(a) Create the project folder](#create-the-project-folder)
-  * [(b) Add #{_package_and_config_files}](#add-config-files).
+  * [(b) Add #{_package_and_config_files}](#add-config-files)
-  * [(c) #{_Install} packages](#install-packages).
+  * [(c) #{_Install} packages](#install-packages)
 
 h3 (a) Create the project folder
 
@@ -150,8 +150,8 @@ block install-packages
         There might be a few `npm WARN` messages along the way — and that is perfectly fine.
 
         We often see an `npm WARN` message after a series of `gyp ERR!` messages.
-        Ignore them. A package may try to re-compile itself using `node-gyp`.
+        Ignore them. A package may try to recompile itself using `node-gyp`.
-        If the re-compile fails, the package recovers (typically with a pre-built version)
+        If the recompile fails, the package recovers (typically with a pre-built version)
         and everything works.
 
         Just make sure there are no `npm ERR!` messages at the end of `npm install`.
@@ -180,7 +180,7 @@ block install-packages
       * `npm run tsc` - runs the TypeScript compiler once
 
       * `npm run tsc:w` - runs the TypeScript compiler in watch mode;
-      the process keeps running, awaiting changes to TypeScript files and re-compiling when it sees them
+      the process keeps running, awaiting changes to TypeScript files and recompiling when it sees them
 
       * `npm run lite` - runs the <a href="https://www.npmjs.com/package/lite-server" target="_blank">lite-server</a>,
       a light-weight, static file server with excellent support for Angular apps that use routing
@@ -194,11 +194,11 @@ block install-packages
   **We're all set.** Let's write some code.
 
 .l-main-section
-h2#root-component Step 2: our first angular component
+h2#root-component Step 2: Our first Angular component
 :marked
   Let's create a folder to hold our application and add a super-simple Angular component.
 
-  **Create an *#{_appDir}* sub-folder** off the project root directory:
+  **Create #{_an} #{_appDir} subfolder** off the project root directory:
 
 code-example.
   mkdir #{_appDir}
@@ -250,7 +250,7 @@ p.
       We apply this function to the component class by prefixing the function with the
       **@** symbol and invoking it with a metadata object, just above the class.
   :marked
-    `@Component` is #{_a} **#{_decorator}** that allows us to associate *metadata* with the
+    `@Component` is #{_a} *#{_decorator}* that allows us to associate *metadata* with the
     component class.
     The metadata tells Angular how to create and use this component.
 
@@ -290,7 +290,7 @@ p.
       as we'll see when we create `main.ts`.
 
 .l-main-section
-h2#main Step 3: add #[code #[+adjExPath('main.ts')]]
+h2#main Step 3: Add #[code #[+adjExPath('main.ts')]]
 
 block create-main
   p.
@@ -337,15 +337,17 @@ block create-main
     Let's make the small extra effort to do it *the right way*.
 
 .l-main-section
-h2#index Step 4: add #[code index.html]
+h2#index Step 4: Add #[code index.html]
 :marked
-  The `index.html` is the web page that hosts the application.
+  In the *#{_indexHtmlDir}* folder
-  In the **#{_indexHtmlDir}** folder
+  create an `index.html` file and paste the following lines into it:
-  create an`index.html` file and paste the following lines:
 
 +makeExample('quickstart/ts/index.html', '', 'index.html')(format='.')
 
 .l-verbose-section
+  :marked
+    The `index.html` file defines the web page that hosts the application.
+
   block index-html-commentary-for-ts
     :marked
       The noteworthy sections of HTML are:
@@ -426,15 +428,15 @@ h2#index Step 4: add #[code index.html]
 
         * We see compiler warnings and errors that are hidden from us in the browser.
 
-        * Pre-compilation simpifies the module loading process and 
+        * Precompilation simpifies the module loading process and
         it's much easier to diagnose problems when this is a separate, external step.
 
-        * Pre-compilation means a faster user experience because the browser doesn't waste time compiling.
+        * Precompilation means a faster user experience because the browser doesn't waste time compiling.
 
-        * We iterate development faster because we only re-compile changed files.
+        * We iterate development faster because we only recompile changed files.
         We notice the difference as soon as the app grows beyond a handful of files.
 
-        * Pre-compilation fits into a continuous integration process of build, test, deploy.
+        * Precompilation fits into a continuous integration process of build, test, deploy.
 
     :marked
       The `System.import` call tells SystemJS to import the `main` file
@@ -445,25 +447,26 @@ h2#index Step 4: add #[code index.html]
       All other modules are loaded upon request
       either by an import statement or by Angular itself.
 
+      ### *&lt;my-app&gt;*
+
   a(id="my-app")
   :marked
-    ### *&lt;my-app&gt;*
     When Angular calls the `bootstrap` function in `main.#{_docsFor}`, it reads the `AppComponent`
     metadata, finds the `my-app` selector, locates an element tag named `my-app`,
     and renders our application's view between those tags.
 
 :marked
   ### Add some style
-  Styles aren't essential but they're nice and the `index.html` assumes we have
+  Styles aren't essential but they're nice, and `index.html` assumes we have
   a stylesheet called `styles.css`.
 
-  Create a `styles.css` in the #{_indexHtmlDir} folder and start styling, perhaps with minimal
+  Create a `styles.css` file in the *#{_indexHtmlDir}* folder and start styling, perhaps with the minimal
-  styles shown below. For the full set of master styles used by the documentation samples
+  styles shown below. For the full set of master styles used by the documentation samples,
-  see this master [styles.css](https://github.com/angular/angular.io/blob/master/public/docs/_examples/styles.css).
+  see [styles.css](https://github.com/angular/angular.io/blob/master/public/docs/_examples/styles.css).
 +makeExcerpt('quickstart/ts/styles.1.css', '', 'styles.css')
 
 .l-main-section
-h2#build-and-run Step 5: build and run the app!
+h2#build-and-run Step 5: Build and run the app!
 block run-app
   :marked
     Open a terminal window and enter this command:
@@ -478,7 +481,7 @@ block run-app
     In a few moments, a browser tab should open and display
 
 figure.image-display
-  img(src='/resources/images/devguide/quickstart/my-first-app.png' alt="Output of quickstart app")
+  img(src='/resources/images/devguide/quickstart/my-first-app.png' alt="Output of QuickStart app")
 
 :marked
   **Great job!**
@@ -502,7 +505,6 @@ block server-watching
 .l-main-section
 :marked
   # Wrap up
-  ## Final project structure and files
 
   Our final project folder structure looks like this:
 block project-file-structure
@@ -522,7 +524,7 @@ block project-file-structure
       .file tsconfig.json
       .file typings.json
 :marked
-  And here are the files:
+  Here are the file contents:
 
 block project-files
   +makeTabs(`