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

Author: wardbell

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

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

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

@@ -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
-    [**node** and **npm**](https://docs.npmjs.com/getting-started/installing-node "Installing Node.js and updating npm").
+    We'll need a base of tools for our application development throughout this guide:
 
-    Now use npm in a terminal (or Windows/Linux command line) to install the **TypeScript compiler** globally
+    - the **TypeScript compiler**
 
-  pre.prettyprint.lang-bash
-    code npm install -g typescript
-
-  :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.
+    - 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).
 
-  pre.prettyprint.lang-bash
-    code npm install -g tsd
+    - **live-server**, a *static server* that runs our app in the browser and reloads the browser when any of the files change.
 
-  :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.
+    **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 live-server
+    code npm install -g typescript tsd live-server
 
   .l-sub-section
     :markdown
-      Our success depends upon installing compatible versions of these tools.
-      Confirm your version numbers in a terminal window with these commands:
+      We depend upon [**node** and **npm**](https://docs.npmjs.com/getting-started/installing-node "Installing Node.js and updating npm")
+      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.
-
-    >***traceur-runtime.js*** to transpile the TypeScript-generated JavaScript into the version of Javascript
-      our browser understands (the version known as "ES5").
+    >***system.js***,  an open-source library that provides module loading.
 
     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 [email protected].37 [email protected]
+    npm i [email protected].38 [email protected] --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
-    which we do with a configuration file named **`tsconfig.json`**.
-    This configuration file also simplifies the TypeScript compilation command
-    that we'll run very soon.
+    We'll add a configuration file named **`tsconfig.json`**
+    to tell the editor how to interpret our TypeScript code and
+    to simplify the TypeScript compilation command 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
-    add a new `index.html` file with the following HTML
+    While in the  **`src`** directory we
+    add a new `index.html` file with the following content
 
-  +makeExample('gettingstarted/ts/src/index.html', null, 'index.html',
-    {pnk: [/(angular2\.dev\.js)/, /(system\.src\.js)/, /(traceur-runtime\.js)/]})
+  +makeExample('gettingstarted/ts/src/index.html', null, 'index.html')
 
   .l-sub-section
     :markdown
-      Notice in the `<head>` element that we're loading the scripts we installed earlier with npm.
-
-      There's an element called `<my-app>` in the `<body>`. This is a placeholder for the *root* of our
-      application. Angular will display our application content here.
+      We're loading the library scripts in the `<head>` element from the  `node_modules`
+      that we installed earlier with npm.
 
-      The final inline script first configures the **`system.js`** module loader and then tells it
-      to import the JavaScript file named `app` in the `app/` folder.
+      In the `<body>` is the app root element called `<my-app>` where Angular displays our application content.
 
-      Subsequent module imports are triggered by a cascade of `import` statements
-      beginning within `app.ts` itself.
+      The final inline script configures the **`system.js`** module loader and tells it
+      to import the *application file* named `app` from within the *folder* named `app/`.
 
       **`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
+
+    * 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
+
+    Perhaps we were expecting something simpler: an Angular library,
+    our application script, and a little HTML. This is all a bit much for a "Hello, World" app.
 
-    We can think of Angular apps as a tree of components.
+    **We have greater ambitions.**
 
-    The `AppComponent` that we've been talking about acts as the top
-    level container - the root of the tree - for the rest of our application.
-    There's nothing special about the `AppComponent` name and we can use whatever makes sense to us.
+    We won't ask Angular to build "Hello, World".
+    We are asking it to help us build sophisticated applications with sophisticated requirements.
+    We're making strategic technology investments to reach our goals
 
-    We've pinned the root component to an element in the `index.html` file where our application will
-    render its view. The element is called `<my-app>` but there is nothing special about this
-    name either.
+    * writing the app in TypeScript for team
+    productivity and maintainability.
 
-    The *root component* loads the initial template for the application.
-    That template could load other components such as menu bars, views, and forms
-    that display information and respond to user gestures.
+    * designing with modules that we can load features dynamically
+    using the latest JavaScript `import` and `export` verbs.
 
-    And these components could load yet more components until the browser page became a deep tree
-    of nested functionality.
+    * running compiler and live-server commands that give us immediate feedback as we make changes.
 
-    We'll walk through examples of these scenarios in the following pages.
+    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].