docs(cli-quickstart): ward's changes

Author: wardbell

public/docs/_examples/cli-quickstart/ts/e2e/app.e2e.ts

@@ -11,7 +11,7 @@ describe('angular2-cli-quickstart App', function() {
   // #docregion title
   it('should display message saying app works', () => {
     page.navigateTo();
-    expect(page.getParagraphText()).toEqual('angular2-cli-quickstart works!');
+    expect(page.getParagraphText()).toEqual('My First Angular 2 App');
   });
   // #enddocregion title
 });

public/docs/_examples/cli-quickstart/ts/src/app/angular2-cli-quickstart.component.spec.ts

@@ -1,3 +1,4 @@
+/* tslint:disable:no-unused-variable */
 // #docregion
 import {
   async,

public/docs/_examples/cli-quickstart/ts/src/app/angular2-cli-quickstart.component.ts

@@ -8,6 +8,6 @@ import {Component} from 'angular2/core';
 })
 // #docregion title
 export class Angular2CliQuickstartApp {
-  title = 'My First Angular 2 App'
+  title = 'My First Angular 2 App';
 }
 // #enddocregion title

public/docs/ts/latest/cli-quickstart.jade

@@ -43,7 +43,7 @@ a(id="devenv")
 
   **Install [node and npm](https://nodejs.org/en/download/)** if not already on your machine.
 
-  Then you **install [Angular-CLI](https://github.com/angular/angular-cli)** and generate a new project by running the following commands:
+  Then **install [Angular-CLI](https://github.com/angular/angular-cli)** and generate a new project by running the following commands:
 
 code-example(format="").
   npm install -g angular-cli
@@ -58,42 +58,43 @@ code-example(format="").
     - link to the style guide
 
 :marked
-  The CLI has also initialized a git repo for the project, so we have everything we need.
+  The CLI has also initialized a git repo for the project.
 
-  **We're all set.** Let's serve our app.
+  **Let's serve our app.**
 
 a(id="serve-and-test")
 .l-main-section
 :marked
   ## Serve & test
-  We're now ready to serve the app that the CLI has generated for us.
 
-  We run `ng serve` to serve, watch our files and rebuild the app whenever we change one.
+  Run `ng serve` to launch the server, watch our files, and rebuild the app whenever we make changes.
 
-  Opening a browser on `http://localhost:4200/` greets us with the following message:
+  Open a browser on `http://localhost:4200/`; the app greets us with a message:
 
 figure.image-display
   img(src='/resources/images/devguide/cli-quickstart/app-works.png' alt="Our app works!")
 
 .alert.is-important
   :marked
-    When using Windows, Angular-CLI commands that involve building the application need an administrator prompt. This is because the CLI build step makes heavy usage of symlinks and in Windows those require admin rights.
+    _Windows Developers_: perform these commands in a console window opened as an administrator.
+    The Angular-CLI build steps create symlinks which require administrator rights under Windows.
 
 .l-verbose-section
   :marked
-    talk about serve
+    talk about the server
 
 :marked
   Now we're ready to write some code... or are we? We certainly could start writing code right now, but our tests would break.
 
 :marked
   ### Tests?
 
-  What tests? Why, the ones the ones that Angular-CLI created with the initial project! They are configured to run on [Google Chrome](https://www.google.com/chrome/) so make sure to have it installed before running them.
+  What tests? The Angular-CLI created tests for our initial project! 
+  They are configured to run on [Google Chrome](https://www.google.com/chrome/) so make sure it is installed before running them.
 
-  To run the end-to-end tests, we leave the current `ng serve` console running, open a new prompt and type `ng e2e`. We should see a the following output after a few console messages:
+  Open a new terminal (or console) window and run the *end-to-end (e2e)* tests with the command: `ng e2e`.
+  Look for the following output after a few console messages:
 code-example(format="").
-  (...)
   Spec started
 
     angular2-cli-quickstart App
@@ -104,16 +105,16 @@ code-example(format="").
 :marked
   Looks all green and good. Always a good sign. 
 
-  Now we run our unit tests once via `ng test --build=false --watch=false`, and we should see a similar message:
+  Keep the server running in the original window and run the *unit tests* with the command: `ng test --build=false --watch=false`. 
+  After more console output, we should see a message like this:
 
 code-example(format="").
-  (...)
   Chrome 49.0.2623 (Windows 10 0.0.0): Executed 2 of 2 SUCCESS (0.016 secs / 0.009 secs)
 
 :marked
-  It's always a good idea to run tests before and after making changes, that way we can guarantee that our apps behave the way we expect them to.
+  It's a good idea to run tests before and after making changes to confirm that our app behaves as we expect it to.
 
-  *Now* we're ready to start coding.
+  *At last* we are ready to write some code.
 
 .l-verbose-section
   :marked
@@ -126,20 +127,21 @@ code-example(format="").
 a(id="edit")
 .l-main-section
 :marked
-  ## Edit our app
+  ## Edit the app
 
-  It's time to make this project more our own. We begin by opening `angular2-cli-quickstart` in our favourite editor.
+  We open the `angular2-cli-quickstart` projecd folder in our favourite editor.
 
-  Our root component is named after the project, and since we initialized the project with the name `angular2-cli-quickstart`, our root component is `Angular2CliQuickstartApp` and can be found in `src/app/angular2-cli-quickstart.component.ts`
+  The root component is named after the project. We created the project with the name `angular2-cli-quickstart`, 
+  so our root component is `Angular2CliQuickstartApp` and can be found in `src/app/angular2-cli-quickstart.component.ts`
 
   Open it and update the title:
 
 +makeExample('cli-quickstart/ts/src/app/angular2-cli-quickstart.component.ts', 'title', 'src/app/angular2-cli-quickstart.component.ts')(format=".")
 
 :marked
-  Our browser reloads automatically, and we see the new message. It's looks nice, but we can make it better.
+  The browser reloads automatically and we see the revised title. That's nice, but we can make look better.
 
-  Open `src/app/angular2-cli-quickstart.component.css` and add in 
+  Open `src/app/angular2-cli-quickstart.component.css` and give the app some style 
 
 +makeExample('cli-quickstart/ts/src/app/angular2-cli-quickstart.component.css', null, 'src/app/angular2-cli-quickstart.component.css')(format=".")
 
@@ -152,32 +154,35 @@ figure.image-display
 :marked
   ### Re-test and fix
 
-  We've made a few changes and we should commit them to Git soon.
+  We've made a few changes that we should commit to source control.
 
-  But first, let's run our tests again. We leave `ng serve` running and on a new console do `ng e2e` and then `ng test --build=false --watch=false`.
+  Before we do, let's run our tests again. 
+  While `ng serve` continues to run in the original window, 
+  enter `ng e2e` again. This time the *e2e* test fails.
 
 code-example(format="").
-  (...)
   1) angular2-cli-quickstart App should display message saying app works
     - Expected 'My First Angular 2 App' to equal 'angular2-cli-quickstart works!'.
 
   Executed 1 of 1 spec (1 FAILED) in 1 sec.
 
+:marked
+  Run the unit tests again: `ng test --build=false --watch=false`. They fail too.
 code-example(format="").
-  (...)
   Chrome 49.0.2623 (Windows 10 0.0.0) App: Angular2CliQuickstart should have as title 'angular2-cli-quickstart works!' FAILED
           Expected 'My First Angular 2 App' to equal 'angular2-cli-quickstart works!'.
-          (...)
+  ...
   Chrome 49.0.2623 (Windows 10 0.0.0): Executed 2 of 2 (1 FAILED) (0.038 secs / 0.022 secs)
 
 :marked
-  Our tests broke - as they should. We changed the title of our app, and our tests were looking for it.
-  
-  Make the following changes to our tests:
+  Our tests broke - as they should. We changed the title of our app, and our tests are looking for the original title.
 
-+makeExample('cli-quickstart/ts/e2e/app.e2e.ts', 'title', 'e2e/app.e2e.ts')(format=".")
+  Fix the expected *title* text in both tests:
 
-+makeExample('cli-quickstart/ts/src/app/angular2-cli-quickstart.component.spec.ts', 'title', 'src/app/angular2-cli-quickstart.component.spec.ts')(format=".")
++makeTabs(
+  'cli-quickstart/ts/e2e/app.e2e.ts, cli-quickstart/ts/src/app/angular2-cli-quickstart.component.spec.ts', 
+  'title, title', 
+  'e2e/app.e2e.ts, src/app/angular2-cli-quickstart.component.spec.ts')(format=".")
 
 :marked
   Run our tests again and... all green! We are back in business.
@@ -190,53 +195,66 @@ code-example(format="").
 a(id="github-pages")
 .l-main-section
 :marked
-  ### Pushing to production
+  ## Push to production (Optional)
 
-  We now have a fully featured app marked green on all tests. Next stop: the production environment.
+  Next stop: the production environment. 
 
   Angular-CLI has a nifty command that helps us push our app onto [GitHub Pages](https://pages.github.com/) hosting.
 
-  To begin we'll need to [create a GitHub Account](https://github.com/join) if we don't have one already. 
-  Afterwards we'll also need to [setup SSH keys on github](https://help.github.com/articles/generating-an-ssh-key/) if we haven't yet.
-    
-  After that's done, run `ng github-pages:deploy`.
+.l-sub-section
+  :marked
+    [Create a free GitHub Account](https://github.com/join) if you don't have one. 
+    and [setup SSH keys](https://help.github.com/articles/generating-an-ssh-key/) 
+    if you haven't done that.
+:marked
+  Close all windows/processes (like `ng serve`!) that are using the app files and folders.
+  
+  Run `ng github-pages:deploy`.
 
 .alert.is-important
   :marked
-    The `ng github-pages:deploy` command will perform a series of git operations that will add and remove files. Make sure you close all windows/processes (like `ng serve`!) that are using the app files and folders, otherwise these git operations might fail.
-    
-    If that happens, we might be left in the `gh-pages` branch instead of the `master` branch. Simply `git checkout master`, close open windows that might be using these files, and try `ng github-pages:deploy`.
+    The `ng github-pages:deploy` command performs a series of git operations that add and remove files. 
+    It can fail if those files are held by another process.
+
+    If the command fails, we might be left in the `gh-pages` branch instead of the `master` branch.
 
+    Run `git branch` and look for the _starred_ branch name. 
+    If it isn't `master`, run `git checkout master`, 
+    close open windows that might be using these files, and try `ng github-pages:deploy` again.
+
 :marked
-  The first time we run this command, it will create a github repository. Every other time we call it, it will use the existing one.
+  This command creates a new github repository the first time we run it. 
+  Subsequent calls use this existing repo.
 
-  The console will prompt us to get a github token that will allow the CLI to create a repo for us - don't worry, it will only be used once and we can safely delete it after the repo is created. Deleting it will invalidate it.
+  The command prompts us for a github token that will allow the CLI to create a repo for us.
+  Don't worry, the token is used only once and we can safely delete it after the repo is created. 
+  Deleting the token invalidates it.
 
-  First go to [https://github.com/settings/tokens](https://github.com/settings/tokens), and click `Generate new token`.
+  ### Get a token
+  Go to [https://github.com/settings/tokens](https://github.com/settings/tokens), and click *Generate new token*.
 
 figure.image-display
   img(src='/resources/images/devguide/cli-quickstart/gh-token-1.png' alt="Generate new token")
 
 :marked
-  Github will ask us to login again, and afterwards we can choose a description and scope for the token.
+  We must login again and then choose a description and scope for the token.
 
-  Name the token `angular-cli`, chose as scope `public_repo` and then `Generate token` at the bottom.
+  Name the token `angular-cli`, chose as scope *public_repo*, and then click *Generate token* at the bottom.
 figure.image-display
   img(src='/resources/images/devguide/cli-quickstart/gh-token-2.png' alt="Description and scope")
 
 :marked
   On the next screen, copy the token, paste it in the console window that asked us for the token, and press enter.
 
-  Keep this page open so that at the end we can delete the token.
+  Keep this page open so we can delete the token when we're done.
 figure.image-display
   img(src='/resources/images/devguide/cli-quickstart/gh-token-3.png' alt="Copy and delete")
 
 :marked
-  The console will also ask us for our github username, and afterwards will create the repository, build our app and deploy it as a Github Page.
-  
-  The whole process should look like this:
+  The command prompts for our github username. Then it creates the repository, builds the app, and deploys it as a Github Page.
+  The entire process we just described looks like this:
 
-code-example(format="." language="bash").
+code-example(format="." language="").
   $ ng github-pages:deploy
   Built project successfully. Stored in "dist/".
 
@@ -277,4 +295,3 @@ code-example(format="." language="bash").
 
   Angular-CLI will help us do the rest, and we can push it online at any time.
 
-