docs(quickstart): incorporate more Igor feedback

Author: wardbell

public/docs/_examples/setup/ts/plnkr.json

@@ -6,5 +6,6 @@
     "app/main.ts",
     "index.html"
   ],
+  "open": "app/app.component.ts",
   "tags": ["quickstart setup"]
 }

public/docs/ts/latest/guide/learning-angular.jade

@@ -2,7 +2,7 @@ block includes
   include ../_util-fns
 
 figure
-  img(src="/resources/images/devguide/intro/people.png" alt="Us" align="left" style="width:200px; margin-left:-40px;margin-right:10px" )
+  img(src="/resources/images/devguide/intro/people.png" width="200px" height="152px" alt="Us" align="left" style="margin-left:-40px;margin-right:10px" )
 :marked
   Everyone learns differently.
   You don't have to read the documentation straight through.  Most pages stand on their own.
@@ -16,6 +16,8 @@ figure
     to a full-featured example that demonstrates the essential characteristics of a professional application:
     a sensible project structure, data binding, master/detail, services, dependency injection, navigation, and remote data access.
 
+a#architecture
+:marked
   1. Read the [Architecture](architecture.html) overview for the big picture.
 
   1. [The Root Module](appmodule.html) introduces the `NgModule` class that tells Angular how to compile and run your application.

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

@@ -1,28 +1,19 @@
 block includes
   include ../_util-fns
 
+a#develop-locally
 :marked
-  ## Trying Angular
-
-  Live coding [Quickstart](../quickstart.html) in the browser is a great way to explore Angular.
-  Links on almost every documentation page will open completed samples in the browser where you can
-  play with the code, share your changes with friends, and download and run the code on your own machine.
-
-  As much fun as this is ...
-  * you can't ship your app in plunker
-  * you aren't always online when writing code
-  * transpiling TypeScript in the browser is slow
-  * the type support, refactoring, and code completion only work in your local IDE
- 
   ## Setup a local development environment
+  The <live-example name=quickstart>QuickStart live-coding</live-example> example is an Angular _playground_.
+  It's not where you'd develop a real application. 
+  You [should develop locally](#why-locally "Why develop locally") on your own machine ... and that's also how we think you should learn Angular.
 
-  Fortunately, setting up a new project in your local development environment is quick and easy
-  with the [**QuickStart seed**](https://github.com/angular/quickstart "Install the github QuickStart repo"),
-  a repository on github. 
+  Setting up a new project on your own machine is quick and easy with the **QuickStart seed**
+  maintained [on github](https://github.com/angular/quickstart "Install the github QuickStart repo"). 
 
   Make sure you have [node and npm installed](#install-node "What if you don't have node?").
   Then ...
-  1. [clone](#clone) or [download](#download) the **QuickStart seed repository**.
+  1. [clone](#clone) or [download](#download) the **QuickStart seed** into your project folder.
   1. [install the `npm` packages](#install-node "What if you don't have node?")
   1. run `npm start` to launch the sample application
 
@@ -51,9 +42,9 @@ code-example(language="sh" class="code-shell").
 
 .l-main-section
 :marked
-  ## What's different about the QuickStart seed?
+  ## What's in the QuickStart seed?
 
-  The QuickStart seed contains the same application as the <live-example name="quickstart">QuickStart live example</live-example>.
+  The **QuickStart seed** contains the same application as the <live-example name="quickstart">QuickStart _playground_</live-example>.
   But there are _many more files_ in the project folder on your machine, 
   most of which you can [learn about later](setup-systemjs-anatomy.html "Setup Anatomy").
 
@@ -76,12 +67,7 @@ code-example(language="sh" class="code-shell").
     app/main.ts
   `)(format='.')
 :marked
-  The [QuickStart](../quickstart.html "Angular QuickStart") sample only shows the `AppComponent` file.
-  It creates the equivalent of `app.module.ts` and `main.ts` internally _for that example only_
-  so the reader can discover Angular without distraction.
-
-  All other guides and cookbooks expect you to have defined these three files explicitly. 
-  Each file has a distinct purpose and evolves independently as the application grows.
+  All guides and cookbooks have _at least these three files_. Each file has a distinct purpose and evolves independently as the application grows.
 
 style td, th {vertical-align: top}
 table(width="100%")
@@ -114,11 +100,11 @@ table(width="100%")
         it's the only viable choice for a sample running in a _live-coding_ environment like Plunker.
         You'll learn about alternative compiling and deployment options later in the documentation.
 
-.l-main-section
-:marked
-  ## Next Step
+.l-sub-section
+  :marked
+    ### Next Step
 
-  If you're new to Angular, try the recommended [learning path](learning-path.html).
+    If you're new to Angular, try the recommended [learning path](learning-angular.html).
 
 a#install-node
 .l-main-section
@@ -140,3 +126,31 @@ a#install-node
     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.
 
+a#why-locally
+.l-main-section
+:marked
+  ## Appdendix: Why develop locally
+
+  <live-example>Live coding</live-example> in the browser is a great way to explore Angular.
+
+  Links on almost every documentation page open completed samples in the browser.
+  You can play with the sample code, share your changes with friends, and download and run the code on your own machine.
+
+  The [QuickStart](../quickstart.html "Angular QuickStart Playground") shows just the `AppComponent` file.
+  It creates the equivalent of `app.module.ts` and `main.ts` internally _for the playground only_.
+  so the reader can discover Angular without distraction.
+  The other samples are based on the QuickStart seed. 
+
+  As much fun as this is ...
+  * you can't ship your app in plunker
+  * you aren't always online when writing code
+  * transpiling TypeScript in the browser is slow
+  * the type support, refactoring, and code completion only work in your local IDE
+
+  Use the <live-example><i>live coding</i></live-example> environment as a _playground_, 
+  a place to try the documentation samples and experiment on your own.
+  It's the perfect place to reproduce a bug when you want to
+  <a href="https://github.com/angular/angular.io/issues/new" target="_blank" title="File a documentation issue">file a documentation issue</a> or
+  <a href="https://github.com/angular/angular/issues/new" target="_blank" title="File an Angular issue">file an issue with Angular itself</a>.
+ 
+  For real development, we strongly recommend [developing locally](#develop-locally).

public/docs/ts/latest/quickstart.jade

@@ -41,8 +41,9 @@ a#typescript
   TypeScript compiles into JavaScript that runs on any modern browser.
   Most developers find it delightful which is why most Angular developers write applications in TypeScript.
   You can write your application in 
-  [other versions of JavaScript](cookbook/ts-to-js.html "TypeScript to JavaScript") or 
-  [Dart](../../dart/latest) if you prefer.
-// will be  
+  [other versions of JavaScript](cookbook/ts-to-js.html "TypeScript to JavaScript")
+  if you prefer.
+// 
+  [Dart](../../dart/latest)
   <a href="https://github.com/angular/dart/latest" target="_blank" title="Dart">Dart</a> if you prefer.
 

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

@@ -79,5 +79,3 @@ figure.image-display
   met in countless applications. Everything has a reason.
 
   And we’ll meet many of the core fundamentals of Angular along the way.
-
-  [Let's get started!](./toh-pt1.html)

public/docs/ts/latest/tutorial/toh-pt1.jade

@@ -1,9 +1,8 @@
 include ../_util-fns
 
 :marked
-  Every story starts somewhere. Our story starts where the [QuickStart](../quickstart.html) ends.
-  
   ## Setup to develop locally
+  Real application development takes place in a local development environment like your machine.
 
   Follow the [setup](../guide/setup.html) instructions for creating a new project
   named <ngio-ex path="angular-tour-of-heroes"></ngio-ex>

public/docs/ts/latest/tutorial/toh-pt6.jade

@@ -618,3 +618,10 @@ block file-summary
     hero-search.component.css,
     rxjs-extensions.ts`
   )
+
+.l-sub-section
+  :marked
+    ### Next Step
+
+    Return to the [learning path](../guide/learning-angular.html#architecture) where 
+    you can read about the concepts and practices you discovered in this tutorial.