docs(quickstart): incorporate more Igor feedback

Author: wardbell

public/_includes/_next-item.jade

@@ -1,19 +1,24 @@
 - var currentPage = false
 - var nextPage = false
+- var hideNextPage = false;
+
 - var data = public.docs[current.path[1]][current.path[2]][current.path[3]]._data
 
 for page, slug in data
 
   // CHECK IF CURRENT PAGE IS SET, THEN SET NEXT PAGE
   if currentPage
     if !nextPage && page.nextable && !page.hide
-      .l-sub-section
-        h3 Next Step
-        a(href="/docs/#{current.path[1]}/#{current.path[2]}/#{current.path[3]}/#{slug}.html") #{page.title}
+      if !hideNextPage
+        .l-sub-section
+          h3 Next Step
+          a(href="/docs/#{current.path[1]}/#{current.path[2]}/#{current.path[3]}/#{slug}.html") #{page.title}
 
       //NEXT PAGE HAS NOW BEEN SET
       - var nextPage = true
 
+  - hideNextPage = page.hideNextPage
+
   // SET CURRENT PAGE FLAG WHEN YOU PASS IT
   if current.path[4] == slug
     - var currentPage = true

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/_data.json

@@ -19,8 +19,8 @@
     "icon": "query-builder",
     "title": "Quickstart",
     "subtitle": "TypeScript",
-    "description": "Get up and running with Angular",
-    "banner": "See Angular in action."
+    "description": "Discover Angular",
+    "banner": "Discover Angular in a live-coding environment."
   },
 
   "tutorial": {

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

@@ -7,11 +7,21 @@
     "basics": true
   },
 
+  "setup": {
+    "title": "Setup for local development",
+    "navTitle": "Setup",
+    "intro": "Install the Angular QuickStart seed for faster, more efficient development on your machine",
+    "nextable": true,
+    "hideNextPage": true,
+    "basics": true
+  },
+
   "learning-angular": {
     "title": "Learning Angular",
     "navTitle": "Learning Angular",
     "intro": "A suggested path through the documentation for Angular newcomers",
     "nextable": true,
+    "hideNextPage": true,
     "basics": true
   },
 
@@ -23,6 +33,7 @@
     "basics": true
   },
 
+
   "appmodule": {
     "title": "AppModule: the root module",
     "navTitle": "The Root Module",
@@ -152,12 +163,6 @@
     "intro": "Developing for content security in Angular applications"
   },
 
-  "setup": {
-    "title": "Setup for local development",
-    "navTitle": "Setup",
-    "intro": "Install the Angular QuickStart seed for faster, more efficient development on your machine"
-  },
-
   "setup-systemjs-anatomy": {
     "title": "Setup Anatomy",
     "intro": "Inside the local development environment for SystemJS"

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

@@ -6,8 +6,9 @@ include ../_util-fns
   that you [bootstrap](#main) to launch the application.
   You can call it anything you want. The conventional name is `AppModule`.
 
-  Most developers start with a simple `AppModule` and evolve it as the application grows. 
-  Here's a minimal `AppModule` from the **QuickStart seed** described on the [setup page](setup.html).
+  The [setup](setup.html) instructions produce a new project with the following minimal `AppModule`.
+  You'll evolve this module as your application grows.
+
 +makeExample('setup/ts/app/app.module.ts','', 'app/app.module.ts')(format='.')
 
 :marked
@@ -22,7 +23,7 @@ include ../_util-fns
   * **_bootstrap_** — the _root_ component that Angular creates and inserts into the `index.html` host web page.
 
   The [Angular Modules (NgModules)](ngmodule.html) guide dives deeply into the details of Angular modules.
-  All you need to know at the moment is a few basics about these three properties.
+  All you need to know at the moment is a few basics about these three properties.  
 
 a#imports
 :marked

public/docs/ts/latest/guide/attribute-directives.jade

@@ -29,7 +29,7 @@ a#directive-overview
   1. Attribute directives—change the appearance or behavior of an element.
 
   *Components* are the most common of the three directives.
-  You saw a component for the first time in the [QuickStart](../quickstart.html#root-component) example.
+  You saw a component for the first time in the [QuickStart](../quickstart.html) example.
 
   *Structural Directives* change the structure of the view. Two examples are [NgFor](template-syntax.html#ngFor) and [NgIf](template-syntax.html#ngIf)
   in the [Template Syntax](template-syntax.html) page.

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

@@ -35,12 +35,14 @@ table(width="100%")
     td <b>Guide</b>
     td
       :marked
-        Learn the Angular basics (you're already here!).
+        Learn the Angular basics (you're already here!) like the setup for local development,
+        displaying data and accepting user input, injecting application services into components,
+        and building simple forms.
   tr(style=top)
     td <b><a href="../api/">API Reference</a></b>
     td
       :marked
-        Authoritative details about each member of the Angular libraries.
+        Authoritative details about each of the Angular libraries.
   tr(style=top)
     td <b><a href="../tutorial/">Tutorial</a></b>
     td

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

@@ -2,21 +2,23 @@ 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.
   Those new to Angular may wish to follow this popular learning path.
   <br class="l-clear-left">
 
 :marked
+  1. [Setup](setup.html "Setup locally withe Quickstart seed") for local Angular development, if you haven't already done so.
+
   1. Take the [*Tour of Heroes* tutorial](../tutorial "Tour of Heroes"). 
 
-    The *Tour of Heroes* takes you step-by-step from the [QuickStart](../quickstart.html) 
+    The *Tour of Heroes* takes you step-by-step from [setup](setup.html)
     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.
 
-  1. Read the [Architecture](architecture.html) overview for the big picture.
+  1. <a id="architecture"></a>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.
 
@@ -32,3 +34,10 @@ figure
   1. [Template Syntax](template-syntax.html) is a comprehensive study of Angular template HTML.
 
   After reading the above sections, feel free to skip around among the other pages on this site.
+
+.l-sub-section
+  :marked
+    ### Next Step
+
+    Try the [tutorial](../tutorial "Tour of Heroes") if you're ready to start coding or 
+    visit the [Architecture](architecture.html "Basic Concepts") guide if you prefer to learn the basic concepts first.

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

@@ -1,30 +1,22 @@
 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 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. [install the `npm` packages](#install-node "What if you don't have node?")
-  1. run `npm start` to launch the sample application
+  1. Create a project folder (you can call it <span ngio-ex>quickstart</span> and rename it later).
+  1. [Clone](#clone "Clone it from github") or [download](#download  "download it from github") 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.
 
 a#clone
 :marked
@@ -33,8 +25,8 @@ a#clone
   Perform the _clone-to-launch_ steps with these terminal commands.
 
 code-example(language="sh" class="code-shell").
-  git clone https://github.com/angular/quickstart.git my-project
-  cd my-project
+  git clone https://github.com/angular/quickstart.git quickstart
+  cd quickstart
   npm install
   npm start
 
@@ -45,16 +37,20 @@ a#download
   and unzip it into your project folder. Then perform the remaining steps with these terminal commands.
 
 code-example(language="sh" class="code-shell").
-  cd my-project
+  cd quickstart
   npm install
   npm start
 
 .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>.
-  But there are _many more files_ in the project folder on your machine, 
+  The **QuickStart seed** contains the same application as the QuickStart playground
+  and even has <live-example>its own _playground_</live-example> 
+  that accomodates development of richer examples in a live coding environment.
+  
+  But it's true purpose is to provide a solid foundation for _local_ development.
+  Consequently, 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").
 
   Focus on the following three TypeScript (`.ts`) files in the **`/app`** folder.
@@ -76,12 +72,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%")
@@ -94,31 +85,34 @@ table(width="100%")
     td <code>app.component.ts</code>
     td
       :marked
-        Defines the same `AppComponent` as the one in the [QuickStart](../quickstart.html).
+        Defines the same `AppComponent` as the one in the QuickStart playground.
         It is the **root** component of what will become a tree of nested components
         as the application evolves. 
   tr
     td <code>app.module.ts</code>
     td
       :marked
-        Defines `AppModule`, the [root module](appmodule.html) that tells Angular how to assemble the application.
+        Defines `AppModule`, the [root module](appmodule.html "AppModule: the root module") that tells Angular how to assemble the application.
         Right now it declares only the `AppComponent`. 
         Soon there will be more components to declare. 
   tr
     td <code>main.ts</code>
     td
       :marked
         Compiles the application with the [JiT compiler](../glossary.html#jit)
-        and [bootstraps](appmodule.html#main) the application to run in the browser.
+        and [bootstraps](appmodule.html#main "bootstrap the application") the application to run in the browser.
         That's a reasonable choice for the development of most projects and
         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, we recommend staying on the [learning path](learning-angular.html).
 
-  If you're new to Angular, try the recommended [learning path](learning-path.html).
+br
+br
 
 a#install-node
 .l-main-section
@@ -140,3 +134,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

@@ -1,19 +1,21 @@
 include _util-fns
 
 :marked
-  The easiest way to get started with Angular is to **<live-example>try the <i>Hello Angular</i> live example</live-example>**.
+  The **QuickStart playground** is the easiest way to discover Angular.
   You don't need to install anything. 
-  Just open it and follow along with the documentation.
-  If you'd rather develop in a local environment, learn how on the [Setup](guide/setup.html) page.
+  Just click the image below, launch the live-coding environment, and start entering code.
 
-  Angular applications are made of _components_. 
-  A _component_ is the combination of an HTML template and a component class that controls a portion of the screen.
-  Here's a super-simple Angular component, written in [TypeScript](#typescript):
+  <live-example embedded img="devguide/quickstart/quickstart-plnkr-big.png"><live-example>
+
+  The QuickStart displays a super-simple Angular component, written in [TypeScript](#typescript):
 
 +makeExample('app/app.component.ts','','app/app.component.ts')(format='.')
 :marked
-  The `@Component` [_decorator_](glossary.html#decorator '"Decorator" explained') function takes a _metadata_ object that 
-  describes how the HTML template and component class work together.
+  Angular applications are made of _components_.
+  A _component_ is the combination of an HTML template and a component class that controls a portion of the screen.
+
+  Every component begins with a `@Component` [_decorator_](glossary.html#decorator '"Decorator" explained') function 
+  that takes a _metadata_ object. The metadata describe how the HTML template and component class work together.
 
   The `selector` property tells Angular to display the component inside a custom `<my-app>` tag in the `index.html`.
 +makeExample('index.html','my-app','index.html (inside <body>)')(format='.')
@@ -30,7 +32,12 @@ include _util-fns
 .l-sub-section
   :marked
     ### Next step
-    Start [learning Angular](guide/learning-angular.html).
+
+    This QuickStart playground is fine for exploring Angular
+    but you won't develop a real application there.
+    
+    You'll want to develop locally on your own machine.
+    Visit the [**setup guide**](guide/setup.html "Install Angular for local development") to learn how.
 
 .l-main-section
 a#typescript
@@ -41,8 +48,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.