Revise for alpha 38 and to confront the surprising complexity in Getting Started in TS

public/docs/_examples/gettingstarted/ts/README.md

@@ -1,8 +0,0 @@
-#Getting Started (TS) for the DevGuide developer
-
-This is the source code for the "Getting Started" Typescript example code.
-
-* **package.json** - as the audience will see it; the example reaches up to the site level **node_modules**
-and the scripts are not supposed to work here.
-
-* **tsd.json** - as the audience will see it; the example reaches up to the example level typings

public/docs/_examples/gettingstarted/ts/package.json

@@ -10,7 +10,7 @@
   "author": "",
   "license": "ISC",
   "dependencies": {
-    "angular2": "^2.0.0-alpha.37",
+    "angular2": "2.0.0-alpha.38",
-    "systemjs": "^0.19.2"
+    "systemjs": "0.19.2"
   }
 }

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

@@ -26,34 +26,27 @@ include ../../../../_includes/_util-fns
   :markdown
     ## Prerequisites
 
-    We'll need a base of tools for all of our application development. We'll only install these once starting with
+    We'll need a base of tools for our application development throughout this guide:
-    [**node** and **npm**](https://docs.npmjs.com/getting-started/installing-node "Installing Node.js and updating npm").
 
-    Now use npm in a terminal (or Windows/Linux command line) to install the **TypeScript compiler** globally
+    - the **TypeScript compiler**
+
+    - the [**tsd package manager**](https://www.npmjs.com/package/tsd "TSD Package Manager") so we can access
+    [TypeScript type definition files](http://definitelytyped.org/ "Definitely Typed") ("`.d.ts`" files).
+
+    - **live-server**, a *static server* that runs our app in the browser and reloads the browser when any of the files change.
+
+    **Open** a terminal (or Windows/Linux command line) and issue the following `npm` command to install them all:
 
   pre.prettyprint.lang-bash
-    code npm install -g typescript
+    code npm install -g typescript tsd live-server
-
-  :markdown
-    Use npm again to install the [**tsd package manager**](https://www.npmjs.com/package/tsd "TSD Package Manager")
-    so we can download TypeScript type definitions files ("`.d.ts`" files)
-    from the [DefinitelyTyped](http://definitelytyped.org/) repository.
-
-  pre.prettyprint.lang-bash
-    code npm install -g tsd
-
-  :markdown
-    Install a node **static server** to serve our application.
-    We'll use **live-server** for this example because it performs a live reload by default and it's
-    fun to watch the browser update as we make changes.
-
-  pre.prettyprint.lang-bash
-    code npm install -g live-server
 
   .l-sub-section
     :markdown
-      Our success depends upon installing compatible versions of these tools.
+      We depend upon [**node** and **npm**](https://docs.npmjs.com/getting-started/installing-node "Installing Node.js and updating npm")
-      Confirm your version numbers in a terminal window with these commands:
+      to install packages such as these global tools.
+
+      We must be sure that we're installing Angular-compatible versions of these packages.
+      Issue the following commands in that same terminal window to confirm that we have the appropriate versions:
     table
       tr
         th Command
@@ -118,26 +111,21 @@ include ../../../../_includes/_util-fns
   :markdown
     ## Install npm packages
 
-    Our application will need some 3rd party JavaScript files:
+    We need to install two JavaScript library packages:
 
     >***angular.js***, the Angular 2 library.
 
-    >***system.js***,  a third-party open-source library that adds module loading functionality to our browser.
+    >***system.js***,  an open-source library that provides module loading.
-
-    >***traceur-runtime.js*** to transpile the TypeScript-generated JavaScript into the version of Javascript
-      our browser understands (the version known as "ES5").
 
     We'll install these package with `npm` and create an npm **`package.json`** configuration file
-    that to maintain future packages as our application evolves.
+    to maintain them as our application evolves.
 
     In a terminal window, go to the **root** folder and type:
     ```
     npm init -y
-    npm install --save angular2@2.0.0-alpha.37 systemjs@0.19.2
+    npm i angular2@2.0.0-alpha.38 systemjs@0.19.2 --save --save-exact
     ```
 
-    `npm` produced a `node_modules` folder that holds these packages and other packages that *they* require.
-
     The essence of our `package.json` should look like this:
   +makeJson('gettingstarted/ts/package.json', { paths: 'name, version, dependencies '})
 
@@ -150,7 +138,6 @@ include ../../../../_includes/_util-fns
     We prefer writing TypeScript apps in editors that understand TypeScript,
     such as [Visual Studio Code](https://code.visualstudio.com/) and
     [Web Storm](https://www.jetbrains.com/webstorm/features/).
-
     Such editors improve the development experience by checking type information and
     displaying API documentation ("intellisense") based on TypeScript definition files (`.d.ts`).
 
@@ -174,16 +161,15 @@ include ../../../../_includes/_util-fns
 
     ### Add the TypeScript configuration file
 
-    We need to tell that editor how to interpret our TypeScript
+    We'll add a configuration file named **`tsconfig.json`**
-    which we do with a configuration file named **`tsconfig.json`**.
+    to tell the editor how to interpret our TypeScript code and
-    This configuration file also simplifies the TypeScript compilation command
+    to simplify the TypeScript compilation command that we'll run very soon.
-    that we'll run very soon.
 
     **Change to the `src` folder and create a `tsconfig.json`** file with the following content:
   +makeJson('gettingstarted/ts/src/tsconfig.json', null, 'tsconfig.json')
 
   :markdown
-    Our project should now look like this:
+    Our project folder structure should now look like this:
     ```
     angular2-getting-started
     ├── node_modules
@@ -199,24 +185,20 @@ include ../../../../_includes/_util-fns
   :markdown
     ## Create an `index.html`
 
-    While in the  **`src`** directory and
+    While in the  **`src`** directory we
-    add a new `index.html` file with the following HTML
+    add a new `index.html` file with the following content
 
-  +makeExample('gettingstarted/ts/src/index.html', null, 'index.html',
+  +makeExample('gettingstarted/ts/src/index.html', null, 'index.html')
-    {pnk: [/(angular2\.dev\.js)/, /(system\.src\.js)/, /(traceur-runtime\.js)/]})
 
   .l-sub-section
     :markdown
-      Notice in the `<head>` element that we're loading the scripts we installed earlier with npm.
+      We're loading the library scripts in the `<head>` element from the  `node_modules`
+      that we installed earlier with npm.
 
-      There's an element called `<my-app>` in the `<body>`. This is a placeholder for the *root* of our
+      In the `<body>` is the app root element called `<my-app>` where Angular displays our application content.
-      application. Angular will display our application content here.
 
-      The final inline script first configures the **`system.js`** module loader and then tells it
+      The final inline script configures the **`system.js`** module loader and tells it
-      to import the JavaScript file named `app` in the `app/` folder.
+      to import the *application file* named `app` from within the *folder* named `app/`.
-
-      Subsequent module imports are triggered by a cascade of `import` statements
-      beginning within `app.ts` itself.
 
       **`app.ts`** is our main application file.  We haven't written it yet. Let's do so now.
 
@@ -277,6 +259,8 @@ include ../../../../_includes/_util-fns
   :markdown
     ## Confirm the final project and file structure
 
+    It should look like this
+
     ```
     angular2-getting-started
     ├── node_modules
@@ -289,11 +273,6 @@ include ../../../../_includes/_util-fns
     │   ├── tsconfig.json
     └── package.json
     ```
-    Seems like overkill for such a trivial application.
-
-    We have ambitions. We aren't learning Angular to build "Hello, World". We intend
-    to build great apps and we anticipate adding meat to these bones
-    in the "Tour of Heroes" tutorial coming up very soon.
 
 .l-main-section
   :markdown
@@ -331,7 +310,7 @@ include ../../../../_includes/_util-fns
     application message:
 
   figure.image-display
-    img(src='/resources/images/examples/setup-example1.png' alt="Example of Todo App")
+    img(src='/resources/images/devguide/getting-started/my-first-app.png' alt="Output of getting started app")
 
   :markdown
     ### Make some changes
@@ -342,27 +321,35 @@ include ../../../../_includes/_util-fns
     The TypeScript compiler running in the first terminal window is watching our source code. It recompiles and produces
     the revised *app.js*.  The *live-server* sees that change and reloads the browser.
 
-    Pretty nice!
-
 .l-main-section
   :markdown
-    ## It's all a tree
+    ## Why so complicated?
+    To display a single line of text we
 
-    We can think of Angular apps as a tree of components.
+    * installed a bunch of unfamiliar tools
+    * loaded a couple of libraries
+    * wrote configuration files for both `npm` and TypeScript
+    * configured something called `system.js` in our `index.html` and
+    told it to import our main file
+    * are compiling TypeScript in one terminal window and running the server in another
 
-    The `AppComponent` that we've been talking about acts as the top
+    Perhaps we were expecting something simpler: an Angular library,
-    level container - the root of the tree - for the rest of our application.
+    our application script, and a little HTML. This is all a bit much for a "Hello, World" app.
-    There's nothing special about the `AppComponent` name and we can use whatever makes sense to us.
 
-    We've pinned the root component to an element in the `index.html` file where our application will
+    **We have greater ambitions.**
-    render its view. The element is called `<my-app>` but there is nothing special about this
-    name either.
 
-    The *root component* loads the initial template for the application.
+    We won't ask Angular to build "Hello, World".
-    That template could load other components such as menu bars, views, and forms
+    We are asking it to help us build sophisticated applications with sophisticated requirements.
-    that display information and respond to user gestures.
+    We're making strategic technology investments to reach our goals
 
-    And these components could load yet more components until the browser page became a deep tree
+    * writing the app in TypeScript for team
-    of nested functionality.
+    productivity and maintainability.
 
-    We'll walk through examples of these scenarios in the following pages.
+    * designing with modules that we can load features dynamically
+    using the latest JavaScript `import` and `export` verbs.
+
+    * running compiler and live-server commands that give us immediate feedback as we make changes.
+
+    The good news is that the overhead of setup is (mostly) behind us.
+    We're about to build a small application that demonstrates the great things
+    we can build with Angular 2.  Join us on the [Tour of Heroes].