docs(dart): update BASICS intro

kwalrath · kwalrath · commit 263416c40a7c · 2016-05-18T10:52:21.000-07:00
Also copy edited the TS version a bit.

NOTE: The TS version (and thus the Dart version) talks about "Reference" and "Resources" sections that don't exist. (API Reference does, but not Reference, as such.)
diff --git a/public/docs/dart/latest/guide/index.jade b/public/docs/dart/latest/guide/index.jade
@@ -1,93 +1,18 @@
-include ../_util-fns
-
-:marked
-  This Developers Guide is a practical guide to Angular for experienced programmers who
-  are building client applications in HTML and Dart.
-figure
-  img(src="/resources/images/devguide/intro/people.png" alt="Us" align="left" style="width:200px; margin-left:-40px;margin-right:10px" )
-:marked
-  We are on a journey together to understand how Angular works and, more importantly,
-  how to make it work for us. We look at our application requirements and we see problems to solve.
-  <br clear="all">
-
-  * How do we get data onto the screen and handle user interactions?
-  * How do we organize our code into manageable, cohesive chunks of functionality that work together?
-  * What are the essential Angular building blocks and how do they help?
-  * How do we minimize routine, mechanical coding in favor of declarative, higher level constructs without losing control?
-
-  This chapter begins the journey.
-
-<a id="how-to-read"></a>
-:marked
-  # How to read this guide
-  Each chapter of this guide targets an Angular feature,
-  showing how to use it to solve a programming problem.
-
-  All the chapters include code snippets ... snippets we can reuse in our own applications.
-  Typically, these snippets are excerpts from a sample application that accompanies the chapter.
-
-  **All the source files** for each sample app are displayed together at the **end of each chapter.**
-
-  <!-- Although a few early chapters are written as tutorials, most later chapters
-  don't explain how to build the accompanying sample.
-  These non-tutorial chapters highlight key points in code but generally don't include the entire source. -->
-
-  <!-- We don't have to read this guide straight through. -->
-  <!-- The "[Cheat Sheet](cheatsheet.html)" is a handy map to Angular overall. -->
-  <!-- A few early chapters are arranged sequentially and best read together to establish a foundation in Angular.
-  But most chapters stand on their own. We can browse to any of them as our interest or some necessity moves us. -->
-
-  Here is a learning path we might follow:
-
-  1. First, be familiar with Dart programming and with web concepts such as
-  the DOM, HTML, and CSS. Dart tutorials such as
-  [Get Started](https://www.dartlang.org/docs/tutorials/get-started/) and
-  [Connect Dart & HTML](https://www.dartlang.org/docs/tutorials/connect-dart-html/)
-  are a great way to start.
-
-  1. Follow the [QuickStart](../quickstart.html), which is the "Hello, World" of Angular 2.
-  It shows how to set up the libraries and tools needed to write *any* Angular app.
-  It ends with a "proof of life", a running Angular app.
-
-  1. Next, read the Developers Guide chapters in order:
-    <!-- TODO: adjust this text once we have non-introductory/tutorial chapters -->
-    1. The rest of this chapter, especially the Architecture overview
-    1. [Displaying Data](displaying-data.html)
-    1. [User Input](user-input.html)
-    1. [Forms](forms.html)
-    <!-- add dependency injection when it exists -->
-    <!-- add text about template syntax, once that exists -->
-
-  1. Consider hopping over to the [TypeScript docs](/docs/ts/latest/)
-     since they're currently ahead of the Dart docs. (We're working on that!)
-     Especially check out the [Tutorial](/docs/ts/latest/tutorial/) and
-     [Cheat Sheet](/docs/ts/latest/guide/cheatsheet.html), and the guide chapters
-     [Dependency Injection](/docs/ts/latest/guide/dependency-injection.html)
-     and [Template Syntax](/docs/ts/latest/guide/template-syntax.html).
-
-  <!-- Follow your own star from there, wherever it leads. -->
-
-  Don't miss the [Cheat Sheet](cheatsheet.html), a handy map to Angular.
-
-<a id="toh"></a>
-.l-main-section
-:marked
-  # Appendix: The Hero Staffing Agency
-
-  There's a backstory to the <!-- the "Tour of Heroes" and --> samples in this guide.
-
-  The world is full of crises large and small.
-  Fortunately, courageous heroes are prepared to take on every challenge.
-  The shadowy Hero Staffing Agency matches crises to heroes.
-
-  We are contract developers, hired by the Agency to build an application to manage their operations.
-  The Agency maintains a stable of heroes with special powers.
-  Ordinary humans submit crises as job requests. The heroes bid to take the job, and the Agency
-  assigns each job accordingly.
-
-  Our application handles every detail of recruiting, tracking, and job assignment.
-  For example, the [Forms](forms.html) chapter features a screen for
-  entering personal information about heroes:
-
-figure.image-display
-  img(src="/resources/images/devguide/forms/hero-form-1.png" width="400px" alt="Clean Form")
+extends ../../../ts/latest/guide/index.jade
+
+block includes
+  include ../_util-fns
+
+block example-links
+  :marked
+    Look for a link to that sample near the top of each page.
+    For example, the sample repo https://github.com/angular-examples/architecture
+    contains the code
+    for the [Architecture](architecture.html) chapter's sample.
+    A running version of that sample is at
+    https://angular-examples.github.io/architecture/.
+
+    A few early chapters are written as tutorials and are clearly marked as such.
+    Most chapters are *not* tutorials.
+    They highlight key points in code rather than explain each step necessary to build the sample.
+    We can still get the full source from the sample repo.
diff --git a/public/docs/ts/latest/guide/index.jade b/public/docs/ts/latest/guide/index.jade
@@ -1,4 +1,5 @@
-include ../_util-fns
+block includes
+  include ../_util-fns
 
 // #docregion intro
 - var langName = current.path[1] == 'ts' ? 'TypeScript' : 'JavaScript'
@@ -17,7 +18,7 @@ figure
 <a id="learning-path"></a>
 :marked
   # Organization
-  
+
   The documentation is divided into major thematic sections, each
   a collection of chapters devoted to that theme.
 // #enddocregion how-to-read-1
@@ -30,8 +31,8 @@ table(width="100%")
     td <b>Tutorial</b>
     td
       :marked
-        A step-by-step, immersive approach to learning Angular. 
-        It begins with the [QuickStart](../quickstart.html), 
+        A step-by-step, immersive approach to learning Angular.
+        It begins with the [QuickStart](../quickstart.html),
         the foundation for every chapter and sample in this documentation,
         followed by the [*Tour of Heroes* tutorial](../tutorial) that
         introduces the major features of Angular in an application context.
@@ -44,7 +45,7 @@ table(width="100%")
     td <b>Developer Guide</b>
     td
       :marked
-        In depth analysis of Angular features and development practices.
+        In-depth analysis of Angular features and development practices.
   tr(style=top)
     td <b>Cookbook</b>
     td
@@ -62,68 +63,70 @@ table(width="100%")
       :marked
         Other places to go for help and information.
 :marked
-  # Learning Path
-  We don't have to read the guide straight through.  Most chapters stand on their own. 
-   
-  We recommend a learning path for those new to Angular. 
+  # Learning path
+  We don't have to read the guide straight through.  Most chapters stand on their own.
+
+  We recommend a learning path for those new to Angular.
   Most of that path runs through the *Basics* section:
 
-  1. Read the [Architecture Overview](architecture.html) to get the big picture.
-  
-  1. Try the [QuickStart](../quickstart.html). The QuickStart is the "Hello, World" of Angular 2. 
-  It shows us how to setup the libraries and tools we'll need to write *any* Angular app. 
-  
-  1. Take the *Tour of Heroes* [Tutorial](../tutorial) which picks up from where the QuickStart leaves off 
-  and builds a simple data-driven app. 
+  1. Read the [Architecture](architecture.html) overview to get the big picture.
+
+  1. Try the [QuickStart](../quickstart.html). The QuickStart is the "Hello, World" of Angular 2.
+  It shows us how to set up the libraries and tools we'll need to write *any* Angular app.
+
+  1. Take the *Tour of Heroes* [Tutorial](../tutorial), which picks up from where the QuickStart leaves off
+  and builds a simple data-driven app.
   Simple, yes, but with the essential characteristics we'd expect of a professional application:
-  a sensible project structure, data binding, master/detail, services, dependency injection, navigation, and remote data access. 
-  
+  a sensible project structure, data binding, master/detail, services, dependency injection, navigation, and remote data access.
+
     Return to the *Basics* section and continue in the suggested order:
-    
+
   1. [Displaying Data](displaying-data.html) explains how to get information on to the screen.
-  
+
   1. [User Input](user-input.html) covers the basics of responding to user behavior.
-  
+
   1. [Forms](forms.html) handle user data entry and validation within the UI.
-  
+
   1. [Dependency Injection](dependency-injection.html) is the way we build large, maintainable applications
-  from small, single purpose parts.
-  
-  1. [Template Syntax](template-syntax.html) is a comprehensive study of Angular template HTML. 
+  from small, single-purpose parts.
+
+  1. [Template Syntax](template-syntax.html) is a comprehensive study of Angular template HTML.
 
   With this foundation, we can read and understand any chapter in the guide.
 // #enddocregion how-to-read-2
 // #docregion the-rest
 :marked
-  # Code Samples
-  
-  Every chapter includes code snippets that we can reuse in our own applications. 
+  # Code samples
+
+  Every chapter includes code snippets that we can reuse in our own applications.
   These snippets are excerpts from a sample application that accompanies the chapter.
-  
-  Look for a link to a running version of that sample near the top of each page
-  such as this [live example](/resources/live-examples/architecture/ts/plnkr.html) from the [Architecture](architecture.html) chapter.
-  
-  The link launches a browser-based code editor where we can inspect, modify, save, and download the code.
-  
-  A few early chapters are written as tutorials and are clearly marked as such. 
-  Most chapters are *not* tutorials. 
-  They highlight key points in code rather than explain each step necessary to build the sample.
-  We can always get the full source by way of the live link.
-  
+
+block example-links
+  :marked
+    Look for a link to a running version of that sample near the top of each page,
+    such as this [live example](/resources/live-examples/architecture/ts/plnkr.html) from the [Architecture](architecture.html) chapter.
+
+    The link launches a browser-based code editor where we can inspect, modify, save, and download the code.
+
+    A few early chapters are written as tutorials and are clearly marked as such.
+    Most chapters are *not* tutorials.
+    They highlight key points in code rather than explain each step necessary to build the sample.
+    We can always get the full source by way of the live link.
+
   ## References
-    
+
   The [Cheat Sheet](cheatsheet.html) lists Angular syntax for common scenarios.
-    
+
   The [Glossary](glossary.html) defines terms that Angular developers should know.
-  
+
   The [API Guide](../api/) is the authority on every public-facing member of the Angular libraries.
- 
+
   # Feedback
-  
+
   We welcome feedback! Leave a comment by clicking the icon in upper right corner of the banner.
-  
-  Post *documentation* issues and pull requests on the 
+
+  Post *documentation* issues and pull requests on the
   [angular.io](https://github.com/angular/angular.io) github repository.
-  
+
   Post issues with *Angular 2 itself* to the [angular](https://github.com/angular/angular) github repository.
 // #enddocregion the-rest
