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].
@@ -22,21 +21,23 @@ block setup-tooling
     [WS]: https://confluence.jetbrains.com/display/WI/Getting+started+with+Dart
     [DT]: https://www.dartlang.org/tools
     [pub]: https://www.dartlang.org/tools/pub
-    
+
 block download-source
   // exclude this section from Dart
 
 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.
 
-block server-watching  
+    h4#dart_to_js_script_rewriter Using dart_to_js_script_rewriter
-  :marked
-    Pub serve is watching and 
-    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.
+    :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
+    To see the new version, just reload the page.
+
+  .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,
@@ -180,10 +200,10 @@ block project-files
       quickstart/dart/pubspec.yaml,
       quickstart/ts/styles.1.css`
     ,null,
-    `app/app.component.ts, 
+    `app/app.component.ts,
-    app/main.ts, 
+    app/main.ts,
     index.html,
-    pubspec.yaml, 
+    pubspec.yaml,
     styles.css`)
 
 block what-next-ts-overhead

public/docs/ts/latest/quickstart.jade

@@ -8,8 +8,8 @@ block includes
   - var _indexHtmlDir = 'project root'
 
 :marked
-  Our QuickStart goal is to build and run a super-simple 
+  Our QuickStart goal is to build and run a super-simple
-  Angular 2 application in #{_Lang}, and 
+  Angular 2 application in #{_Lang}, and
   establish a development environment for the remaining documentation samples
   that also can be the foundation for real world applications.
 
@@ -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)
 
@@ -55,8 +55,8 @@ block download-source
   .callout.is-helpful
     header Download the source
     :marked
-      Instead of following each step of these instructions, we can 
+      Instead of following each step of these instructions, we can
-      [download the QuickStart source](https://github.com/angular/quickstart/blob/master/README.md) 
+      [download the QuickStart source](https://github.com/angular/quickstart/blob/master/README.md)
       from github and follow its brief instructions.
 
 .l-main-section
@@ -68,10 +68,10 @@ button(class="verbose on md-primary md-button md-ink-ripple", type="button", onc
   :marked
     *Explanations* describe the concepts and reasons behind the instructions.
     Explanations have a thin border on the left like *this* block of text.
-        
+
-    Click *Hide Explanations* to show only the instructions. 
+    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
     We'll see many code blocks as we build the QuickStart app. They're all easy to copy and paste:
@@ -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
 
@@ -103,7 +103,7 @@ block package-and-config-files
   p Add the following package definition and configuration files to the project folder:
   ul
     li.
-      #[b package.json] lists packages the QuickStart app depends on and 
+      #[b package.json] lists packages the QuickStart app depends on and
       defines some useful scripts.
       See #[a(href="guide/npm-packages.html") Npm Package Configuration] for details.
     li.
@@ -115,7 +115,7 @@ block package-and-config-files
     li.
       #[b systemjs.config.js], the SystemJS configuration file.
       See discussion #[a(href="#systemjs") below].
- 
+
   a#config-files
   +makeTabs(`
       quickstart/ts/package.1.json,
@@ -132,7 +132,7 @@ block package-and-config-files
 h3#install-packages (c) #{_Install} packages
 block install-packages
   :marked
-    We install the packages listed in `package.json` using `npm`. Enter the 
+    We install the packages listed in `package.json` using `npm`. Enter the
     following command in a terminal window (command window in Windows):
 
   code-example(language="sh").
@@ -140,18 +140,18 @@ block install-packages
 
   .alert.is-important
     :marked
-      Scary <span style="color:red; font-weight: bold">error messages in red</span> may appear **during** install. 
+      Scary <span style="color:red; font-weight: bold">error messages in red</span> may appear **during** install.
       The install typically recovers from these errors and finishes successfully.
     .l-verbose-section(class="l-verbose-inherit")
       :marked
         #### npm errors and warnings
 
-        All is well if there are no console messages starting with `npm ERR!` *at the end* of **npm install**. 
+        All is well if there are no console messages starting with `npm ERR!` *at the end* of **npm install**.
         There might be a few `npm WARN` messages along the way &mdash; and that is perfectly fine.
 
-        We often see an `npm WARN` message after a series of `gyp ERR!` messages. 
+        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`.
@@ -160,8 +160,8 @@ block install-packages
     :marked
       #### Adding the libraries and packages we need with *npm*
       Angular application developers rely on the _[npm](https://docs.npmjs.com)_
-      package manager to install the libraries and packages their apps require. 
+      package manager to install the libraries and packages their apps require.
-      The Angular team recommends the starter-set of packages specified in the 
+      The Angular team recommends the starter-set of packages specified in the
       `dependencies` and `devDependencies` sections.
       See the [npm packages](guide/npm-packages.html) chapter for details.
 
@@ -170,7 +170,7 @@ block install-packages
     +makeJson('quickstart/ts/package.1.json',{ paths: 'scripts'}, 'package.json (scripts)')(format=".")
 
     :marked
-      We execute most npm scripts in the following way: `npm run` followed by a *script-name*. 
+      We execute most npm scripts in the following way: `npm run` followed by a *script-name*.
       Some commands (such as `start`) don't require the `run` keyword.
 
       Here's what these scripts do:
@@ -179,10 +179,10 @@ block install-packages
 
       * `npm run tsc` - runs the TypeScript compiler once
 
-      * `npm run tsc:w` - runs the TypeScript compiler in watch mode; 
+      * `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>, 
+      * `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
 
       * `npm run typings` - runs the [*typings* tool](#{_typingsUri}) separately
@@ -194,26 +194,26 @@ 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}
 
 a#app-component
 p.
-  #[b Create the component file] 
+  #[b Create the component file]
   #[code #[+adjExPath('app/app.component.ts')]] (in this newly created directory) with the following content:
 
 +makeExample('quickstart/ts/app/app.component.ts', '', 'app/app.component.ts')(format='.')
-  
+
 .l-verbose-section
   :marked
     ### AppComponent is the root of the application
-    
+
     Every Angular app has at least one **root component**, conventionally named `AppComponent`,
     that hosts the client user experience.
     Components are the basic building blocks of Angular applications.
@@ -221,14 +221,14 @@ p.
 
     This QuickStart has only one, extremely simple component.
     But it has the essential structure of every component we'll ever write:
-    
+
     * One or more [import](#component-import)
-    statements to reference the things we need.  
+    statements to reference the things we need.
     * A [@Component #{_decorator}](#component-decorator)
     that tells Angular what template to use and how to create the component.
     * A [component class](#component-class)
     that controls the appearance and behavior of a view through its template.
-    
+
   a#component-import
   :marked
     ### Import
@@ -236,8 +236,8 @@ p.
     Angular apps are modular. They consist of many files each dedicated to a purpose.
     Angular itself is modular. It is a collection of library modules
     each made up of several, related features that we'll use to build our application.
-    
+
-    When we need something from a module or library, we import it. 
+    When we need something from a module or library, we import it.
     Here we import the Angular 2 core so that our component code can have access to
     the `@Component` #{_decorator}.
 
@@ -247,10 +247,10 @@ p.
   +ifDocsFor('ts')
     :marked
       `Component` is a *decorator function* that takes a *metadata object* as argument.
-      We apply this function to the component class by prefixing the function with the 
+      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.
 
@@ -268,9 +268,9 @@ p.
 
     The **template** specifies the component's companion template,
     written in an enhanced form of HTML that tells Angular how to render this component's view.
-    
+
     >Our template is a single line of HTML announcing "*My First Angular 2 App*".
-    
+
     >A more advanced template could contain data bindings to component properties
     and might identify other application components which have their own templates.
     These templates might identify yet other components.
@@ -281,16 +281,16 @@ p.
     At the bottom of the file is an empty, do-nothing class named `AppComponent`.
   +makeExcerpt('quickstart/ts/app/app.component.ts', 'class', 'app/app.component.ts (class)')
   :marked
-    When we're ready to build a substantive application, 
+    When we're ready to build a substantive application,
-    we can expand this class with properties and application logic. 
+    we can expand this class with properties and application logic.
     Our `AppComponent` class is empty because we don't need it to do anything in this QuickStart.
   +ifDocsFor('ts')
     :marked
       We **export** `AppComponent` so that we can **import** it elsewhere in our application,
       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.
@@ -305,47 +305,49 @@ block create-main
 
     1. Angular's browser `bootstrap` function
     1. The application root component, `AppComponent`.
-    
+
     Then we call `bootstrap` with `AppComponent`.
- 
+
     ### Bootstrapping is platform-specific
     Notice that we import the `bootstrap` function from `#{_angular_browser_uri}`,
     not `#{_angular_core_uri}`.
     Bootstrapping isn't core because there isn't a single way to bootstrap the app.
     True, most applications that run in a browser call the bootstrap function from
     this library.
-      
+
-    But it is possible to load a component in a different environment. 
+    But it is possible to load a component in a different environment.
     We might load it on a mobile device with [Apache Cordova](https://cordova.apache.org/) or [NativeScript](https://www.nativescript.org/).
     We might wish to render the first page of our application on the server
-    to improve launch performance or facilitate 
+    to improve launch performance or facilitate
     [SEO](http://www.google.com/webmasters/docs/search-engine-optimization-starter-guide.pdf).
     These targets require a different kind of bootstrap function that we'd import from a different library.
-  
+
     ### Why create separate *main.#{_docsFor}* and app component files?
-    
+
-    Both `main.#{_docsFor}` and the app component files are tiny. 
+    Both `main.#{_docsFor}` and the app component files are tiny.
     This is just a QuickStart.
     We could have merged these two files into one
     and spared ourselves some complexity.
-    
+
     We'd rather demonstrate the proper way to structure an Angular application.
-    App bootstrapping is a separate concern from presenting a view. 
+    App bootstrapping is a separate concern from presenting a view.
     Mixing concerns creates difficulties down the road.
-    We might launch the `AppComponent` in multiple environments with different bootstrappers. 
+    We might launch the `AppComponent` in multiple environments with different bootstrappers.
     Testing the component is much easier if it doesn't also try to run the entire application.
     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:
@@ -375,10 +377,10 @@ h2#index Step 4: add #[code index.html]
       added the `systemjs.config.js` file to the project root.
       There are alternatives that work just fine including the well-regarded
       [webpack](guide/webpack.html).
-      SystemJS happens to be a good choice. 
+      SystemJS happens to be a good choice.
       But we want to be clear that it was a *choice* and not a *preference*.
 
-      All module loaders require configuration and all loader configuration 
+      All module loaders require configuration and all loader configuration
       becomes complicated rather quickly as soon as the file structure diversifies and
       we start thinking about building for production and performance.
 
@@ -386,28 +388,28 @@ h2#index Step 4: add #[code index.html]
       Learn more about SystemJS configuration
       <a href="https://github.com/systemjs/systemjs/blob/master/docs/config-api.md" target="_blank">here</a>.
 
-      With those cautions in mind, what are we doing in the 
+      With those cautions in mind, what are we doing in the
       QuickStart [`systemjs.config.js` configuration file we added earlier](#config-files)?
       First, we create a map to tell SystemJS where to look when we import some module.
-      Then, we register all our packages to SystemJS: 
+      Then, we register all our packages to SystemJS:
       all the project dependencies and our application package, `app`.
 
     .l-sub-section
       :marked
-        Our QuickStart doesn't use all of the listed packages 
+        Our QuickStart doesn't use all of the listed packages
         but any substantial application will want many of them
         and all of the listed packages are required by at least one of the documentation samples.
 
         There is no runtime harm in listing packages that we don't need as they will only be loaded when requested.
     :marked
-      The `app` package tells SystemJS what to do when it sees a request for a 
+      The `app` package tells SystemJS what to do when it sees a request for a
-      module from the `app/` folder. 
+      module from the `app/` folder.
 
       Our QuickStart makes such requests when one of its
       application TypeScript files has an import statement like this:
     +makeExcerpt('quickstart/ts/app/main.ts', 'app-component', 'main.ts (excerpt)')
     :marked
-      Notice that the module name (after `from`) does not mention a filename extension. 
+      Notice that the module name (after `from`) does not mention a filename extension.
       In the configuration we tell SystemJS to default the extension to `js`, a JavaScript file.
 
       That makes sense because we transpile TypeScript to JavaScript
@@ -417,53 +419,54 @@ h2#index Step 4: add #[code index.html]
       :marked
         #### Transpiling in the browser
         In the live example on plunker we transpile (AKA compile) to JavaScript in the browser
-        on the fly. _That's fine for a demo_. 
+        on the fly. _That's fine for a demo_.
-        
+
         **Do not transpile in the browser during development or for production**.
 
-        We strongly recommend transpiling (AKA compiling) to JavaScript during a build phase 
+        We strongly recommend transpiling (AKA compiling) to JavaScript during a build phase
         before running the application for several reasons including:
 
         * 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 
+      The `System.import` call tells SystemJS to import the `main` file
       (`main.js` ... after transpiling `main.ts`, remember?);
       `main` is where we tell Angular to launch the application.
-      We also catch and log launch errors to the console. 
+      We also catch and log launch errors to the console.
 
       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!**
@@ -488,9 +491,9 @@ block build-app
 
 :marked
   ## Make some changes
-  
+
   Try changing the message to "My SECOND Angular 2 app".
-block server-watching  
+block server-watching
   :marked
     The TypeScript compiler and `lite-server` are watching.
     They should detect the change, recompile the TypeScript into JavaScript,
@@ -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(`
@@ -535,11 +537,11 @@ block project-files
       quickstart/ts/styles.1.css,
       quickstart/ts/systemjs.config.1.js`
     ,null,
-    `app/app.component.ts, 
+    `app/app.component.ts,
-    app/main.ts, 
+    app/main.ts,
     index.html,
-    package.json, 
+    package.json,
-    tsconfig.json, 
+    tsconfig.json,
     typings.json,
     styles.css,
     systemjs.config.js`)
@@ -556,11 +558,11 @@ block project-files
   **We have greater ambitions!**
 block what-next-ts-overhead
   :marked
-    The good news is that the overhead of setup is (mostly) behind us. 
+    The good news is that the overhead of setup is (mostly) behind us.
     We'll probably only touch the `package.json` to update libraries.
     We'll likely open `index.html` only if we need to add a library or some css stylesheets.
 :marked
-  We're about to take the next step and build a small application that 
+  We're about to take the next step and build a small application that
   demonstrates the great things we can build with Angular 2.
 
   Join us on the [Tour of Heroes Tutorial](./tutorial)!