docs(intro): heavily revised based on Jeremy W feedback

Closes 717. See also #703
This commit is contained in:
Ward Bell 2016-01-18 00:32:36 -08:00
parent 58ceaffca3
commit 8183ad6f54
1 changed files with 33 additions and 63 deletions

View File

@ -1,53 +1,26 @@
include ../../../../_includes/_util-fns
:marked
The Developer Guide is a practical guide to Angular for experienced programmers who
are building client applications in HTML and JavaScript.
figure
img(src="/resources/images/devguide/intro/people.png" alt="Us" align="left" style="width:200px; margin-left:-40px;margin-right:10px" )
:marked
The Developer Guide is a practical guide to Angular for experienced programmers who
are building client applications in HTML and JavaScript.
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.
how to make it work for us. This chapter begins the journey.
<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
The chapters of this guide target an Angular feature and how to use it to solve a programming problem.
## Chapters
The guide consists of chapters devoted to the challenges of building an application and
meeting those challenges with Angular.
A few early chapters are written as tutorials and are clearly marked as such.
Most chapters are *not* tutorials and do not explain every step necessary to build the accompanying sample.
These chapters highlight key points in code but generally don't include the entire source.
We can get that source by way of the live link to the chapter's code sample.
## Code Samples
Every chapter includes code snippets ... snippets we can reuse in our own applications.
Typically, these snippets are excerpts from a running sample application that accompanies the chapter.
We usually find a link to a live version of that sample near the top of the chapter ... like this one.
[Live Example](/resources/live-examples/architecture/ts/plnkr.html)
This link opens in a browser and runs the sample code supporting this chapter's architecture overview.
We can inspect, modify, save, and download the code.
## Learning Path
We don't have to read this guide straight through. Most chapters stand on their own.
We can browse to any of them as our interest or some necessity moves us.
We don't have to read the guide straight through. Most chapters stand on their own.
But there is a learning path for those of us who are new to Angular.
There is a learning path for those of us who are new to Angular.
1. Read the [Architecture Overview](architecture.html) to get the big picture.
@ -59,10 +32,7 @@ figure
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.
The final iteration of the "[Tour of Heroes](#toh)" is a positive answer to that most important question:
***can we build an Angular 2 application that does what we need it to do?***
Return from the tutorial to the basic chapters of this Developers Guide.
Return to the developers guide.
1. [Displaying Data](displaying-data.html) explains how to get information on to the screen.
@ -77,33 +47,33 @@ figure
With this foundation, we can read and understand any chapter in the guide.
## Other Resources
Don't neglect the other documentation resources.
## Code Samples
The "[Cheat Sheet](cheatsheet.html)" is a handy map to Angular overall.
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.
## Other Resources
The [Cheat Sheet](cheatsheet.html) lists Angular syntax for common scenarios.
The [API Guide](../api/) is the authority on every public-facing member of the Angular libraries.
## Feedback
<a id="toh"></a>
.l-main-section
:marked
# Appendix: The Hero Staffing Agency
The final phase of the tutorial Tour of Heroes app runs like this.
figure.image-display
img(src='/resources/images/devguide/toh/toh-anim.gif' alt="Tour of Heroes in Action" height="300px")
:marked
There's a backstory to the "Tour of Heroes" and every sample in this guide.
We welcome feedback! Leave a comment by clicking the icon in upper right corner of the banner.
The world is full of crises large and small.
Fortunately, there are courageous heroes prepared to take on every challenge.
The shadowy "Hero Staffing Agency" matches crises to heroes.
Post *documentation* issues and pull requests on the
[angular.io](https://github.com/angular/angular.io) github repository.
We are contract developers, hired by The Agency to build an Angular application to manage their operations.
The Agency maintains a stable of heroes with special powers.
Ordinary humans call the agency, looking for help with their personal or global crises.
The Agency triages the crises and turns them into job requests.
The heroes on staff bid to take a job and The Agency
assigns each job accordingly.
Post issues with *Angular 2 itself* to the [angular](https://github.com/angular/angular) github repository.
Our application handles every detail of recruiting, tracking and job assignment.