docs(README.md): minor typo/wording/style improvements

Closes angular#384

Author: gkalpak

README.md

@@ -1,8 +1,7 @@
-# angular-seed — the seed for AngularJS apps
+# `angular-seed` — the seed for AngularJS apps
 
-This project is an application skeleton for a typical [AngularJS](http://angularjs.org/) web app.
-You can use it to quickly bootstrap your angular webapp projects and dev environment for these
-projects.
+This project is an application skeleton for a typical [AngularJS][angularjs] web app. You can use it
+to quickly bootstrap your angular webapp projects and dev environment for these projects.
 
 The seed contains a sample AngularJS application and is preconfigured to install the Angular
 framework and a bunch of development and testing tools for instant web development gratification.
@@ -12,40 +11,39 @@ The seed app doesn't do much, just shows how to wire two controllers and views t
 
 ## Getting Started
 
-To get you started you can simply clone the angular-seed repository and install the dependencies:
+To get you started you can simply clone the `angular-seed` repository and install the dependencies:
 
 ### Prerequisites
 
-You need git to clone the angular-seed repository. You can get git from
-[http://git-scm.com/](http://git-scm.com/).
+You need git to clone the `angular-seed` repository. You can get git from [here][git].
 
-We also use a number of node.js tools to initialize and test angular-seed. You must have node.js and
-its package manager (npm) installed.  You can get them from [http://nodejs.org/](http://nodejs.org/).
+We also use a number of Node.js tools to initialize and test `angular-seed`. You must have Node.js
+and its package manager (npm) installed. You can get them from [here][node].
 
-### Clone angular-seed
+### Clone `angular-seed`
 
-Clone the angular-seed repository using [git][git]:
+Clone the `angular-seed` repository using git:
 
 ```
 git clone https://github.com/angular/angular-seed.git
 cd angular-seed
 ```
 
-If you just want to start a new project without the angular-seed commit history then you can do:
+If you just want to start a new project without the `angular-seed` commit history then you can do:
 
-```bash
+```
 git clone --depth=1 https://github.com/angular/angular-seed.git <your-project-name>
 ```
 
 The `depth=1` tells git to only pull down one commit worth of historical data.
 
 ### Install Dependencies
 
-We have two kinds of dependencies in this project: tools and angular framework code.  The tools help
+We have two kinds of dependencies in this project: tools and Angular framework code. The tools help
 us manage and test the application.
 
-* We get the tools we depend upon via `npm`, the [node package manager][npm].
-* We get the angular code via `bower`, a [client-side code package manager][bower].
+* We get the tools we depend upon via `npm`, the [Node package manager][npm].
+* We get the Angular code via `bower`, a [client-side code package manager][bower].
 * In order to run the end-to-end tests, you will also need to have the
   [Java Development Kit (JDK)][jdk] installed on your machine. Check out the section on
   [end-to-end testing](#e2e-testing) for more info.
@@ -56,27 +54,26 @@ We have preconfigured `npm` to automatically run `bower` so we can simply do:
 npm install
 ```
 
-Behind the scenes this will also call `bower install`.  You should find that you have two new
-folders in your project.
+Behind the scenes this will also call `bower install`. After that, you should find out that you have
+two new folders in your project.
 
 * `node_modules` - contains the npm packages for the tools we need
-* `app/bower_components` - contains the angular framework files
+* `app/bower_components` - contains the Angular framework files
 
 *Note that the `bower_components` folder would normally be installed in the root folder but
-angular-seed changes this location through the `.bowerrc` file.  Putting it in the app folder makes
-it easier to serve the files by a webserver.*
+`angular-seed` changes this location through the `.bowerrc` file. Putting it in the `app` folder
+makes it easier to serve the files by a web server.*
 
 ### Run the Application
 
-We have preconfigured the project with a simple development web server.  The simplest way to start
+We have preconfigured the project with a simple development web server. The simplest way to start
 this server is:
 
 ```
 npm start
 ```
 
-Now browse to the app at `http://localhost:8000/index.html`.
-
+Now browse to the app at [`localhost:8000/index.html`][local-app-url].
 
 
 ## Directory Layout
@@ -109,32 +106,34 @@ e2e-tests/            --> end-to-end tests
   scenarios.js          --> end-to-end scenarios to be run by Protractor
 ```
 
+
 ## Testing
 
-There are two kinds of tests in the angular-seed application: Unit tests and end-to-end tests.
+There are two kinds of tests in the `angular-seed` application: Unit tests and end-to-end tests.
 
 ### Running Unit Tests
 
-The angular-seed app comes preconfigured with unit tests. These are written in
-[Jasmine][jasmine], which we run with the [Karma Test Runner][karma]. We provide a Karma
-configuration file to run them.
+The `angular-seed` app comes preconfigured with unit tests. These are written in [Jasmine][jasmine],
+which we run with the [Karma][karma] test runner. We provide a Karma configuration file to run them.
 
-* the configuration is found at `karma.conf.js`
-* the unit tests are found next to the code they are testing and are named as `..._test.js`.
+* The configuration is found at `karma.conf.js`.
+* The unit tests are found next to the code they are testing and have an `_test.js` suffix (e.g.
+  `view1_test.js`).
 
 The easiest way to run the unit tests is to use the supplied npm script:
 
 ```
 npm test
 ```
 
-This script will start the Karma test runner to execute the unit tests. Moreover, Karma will sit and
-watch the source and test files for changes and then re-run the tests whenever any of them change.
+This script will start the Karma test runner to execute the unit tests. Moreover, Karma will start
+watching the source and test files for changes and then re-run the tests whenever any of them
+changes.
 This is the recommended strategy; if your unit tests are being run every time you save a file then
 you receive instant feedback on any changes that break the expected code functionality.
 
-You can also ask Karma to do a single run of the tests and then exit.  This is useful if you want to
-check that a particular version of the code is operating as expected.  The project contains a
+You can also ask Karma to do a single run of the tests and then exit. This is useful if you want to
+check that a particular version of the code is operating as expected. The project contains a
 predefined script to do this:
 
 ```
@@ -145,32 +144,34 @@ npm run test-single-run
 <a name="e2e-testing"></a>
 ### Running End-to-End Tests
 
-The angular-seed app comes with end-to-end tests, again written in [Jasmine][jasmine]. These tests
-are run with the [Protractor][protractor] End-to-End test runner.  It uses native events and has
+The `angular-seed` app comes with end-to-end tests, again written in [Jasmine][jasmine]. These tests
+are run with the [Protractor][protractor] End-to-End test runner. It uses native events and has
 special features for Angular applications.
 
-* the configuration is found at `e2e-tests/protractor-conf.js`
-* the end-to-end tests are found in `e2e-tests/scenarios.js`
+* The configuration is found at `e2e-tests/protractor-conf.js`.
+* The end-to-end tests are found in `e2e-tests/scenarios.js`.
 
 Protractor simulates interaction with our web app and verifies that the application responds
-correctly. Therefore, our web server needs to be serving up the application, so that Protractor
-can interact with it.
+correctly. Therefore, our web server needs to be serving up the application, so that Protractor can
+interact with it.
+
+**Before starting Protractor, open a separate terminal window and run:**
 
 ```
 npm start
 ```
 
-In addition, since Protractor is built upon WebDriver we need to install this.  The angular-seed
-project comes with a predefined script to do this:
+In addition, since Protractor is built upon WebDriver, we need to ensure that it is installed and
+up-to-date. The `angular-seed` project is configured to do this automatically before running the
+end-to-end tests, so you don't need to worry about it. If you want to manually update the WebDriver,
+you can run:
 
 ```
 npm run update-webdriver
 ```
 
-This will download and install the latest version of the stand-alone WebDriver tool.
-
-Once you have ensured that the development web server hosting our application is up and running
-and WebDriver is updated, you can run the end-to-end tests using the supplied npm script:
+Once you have ensured that the development web server hosting our application is up and running, you
+can run the end-to-end tests using the supplied npm script:
 
 ```
 npm run protractor
@@ -180,8 +181,8 @@ This script will execute the end-to-end tests against the application being host
 development server.
 
 **Note:**
-Under the hood, Protractor uses the [Selenium Standalone Server][selenium], which in turn requires 
-the [Java Development Kit (JDK)][jdk] to be installed on your local machine. Check this by running 
+Under the hood, Protractor uses the [Selenium Standalone Server][selenium], which in turn requires
+the [Java Development Kit (JDK)][jdk] to be installed on your local machine. Check this by running
 `java -version` from the command line.
 
 If JDK is not already installed, you can download it [here][jdk-download].
@@ -204,91 +205,91 @@ respectively.
 
 ## Loading Angular Asynchronously
 
-The angular-seed project supports loading the framework and application scripts asynchronously.  The
-special `index-async.html` is designed to support this style of loading.  For it to work you must
-inject a piece of Angular JavaScript into the HTML page.  The project has a predefined script to help
-do this.
+The `angular-seed` project supports loading the framework and application scripts asynchronously.
+The special `index-async.html` is designed to support this style of loading. For it to work you must
+inject a piece of Angular JavaScript into the HTML page. The project has a predefined script to help
+do this:
 
 ```
 npm run update-index-async
 ```
 
-This will copy the contents of the `angular-loader.js` library file into the `index-async.html` page.
-You can run this every time you update the version of Angular that you are using.
+This will copy the contents of the `angular-loader.js` library file into the `index-async.html`
+page. You can run this every time you update the version of Angular that you are using.
 
 
 ## Serving the Application Files
 
-While angular is client-side-only technology and it's possible to create angular webapps that
-don't require a backend server at all, we recommend serving the project files using a local
-webserver during development to avoid issues with security restrictions (sandbox) in browsers. The
-sandbox implementation varies between browsers, but quite often prevents things like cookies, xhr,
-etc to function properly when an html page is opened via `file://` scheme instead of `http://`.
-
+While Angular is client-side-only technology and it is possible to create Angular web apps that
+do not require a backend server at all, we recommend serving the project files using a local
+web server during development to avoid issues with security restrictions (sandbox) in browsers. The
+sandbox implementation varies between browsers, but quite often prevents things like cookies, XHR,
+etc to function properly when an HTML page is opened via the `file://` scheme instead of `http://`.
 
 ### Running the App during Development
 
-The angular-seed project comes preconfigured with a local development webserver.  It is a node.js
-tool called [http-server][http-server].  You can start this webserver with `npm start` but you may choose to
-install the tool globally:
+The `angular-seed` project comes preconfigured with a local development web server. It is a Node.js
+tool called [http-server][http-server]. You can start this web server with `npm start`, but you may
+choose to install the tool globally:
 
 ```
 sudo npm install -g http-server
 ```
 
-Then you can start your own development web server to serve static files from a folder by
-running:
+Then you can start your own development web server to serve static files from a folder by running:
 
 ```
 http-server -a localhost -p 8000
 ```
 
-Alternatively, you can choose to configure your own webserver, such as apache or nginx. Just
+Alternatively, you can choose to configure your own web server, such as Apache or Nginx. Just
 configure your server to serve the files under the `app/` directory.
 
-
 ### Running the App in Production
 
 This really depends on how complex your app is and the overall infrastructure of your system, but
-the general rule is that all you need in production are all the files under the `app/` directory.
+the general rule is that all you need in production are the files under the `app/` directory.
 Everything else should be omitted.
 
-Angular apps are really just a bunch of static html, css and js files that just need to be hosted
+Angular apps are really just a bunch of static HTML, CSS and JavaScript files that need to be hosted
 somewhere they can be accessed by browsers.
 
-If your Angular app is talking to the backend server via xhr or other means, you need to figure
-out what is the best way to host the static files to comply with the same origin policy if
-applicable. Usually this is done by hosting the files by the backend server or through
-reverse-proxying the backend server(s) and webserver(s).
+If your Angular app is talking to the backend server via XHR or other means, you need to figure out
+what is the best way to host the static files to comply with the same origin policy if applicable.
+Usually this is done by hosting the files by the backend server or through reverse-proxying the
+backend server(s) and web server(s).
 
 
 ## Continuous Integration
 
 ### Travis CI
 
-[Travis CI][travis] is a continuous integration service, which can monitor GitHub for new commits
-to your repository and execute scripts such as building the app or running tests. The angular-seed
+[Travis CI][travis] is a continuous integration service, which can monitor GitHub for new commits to
+your repository and execute scripts such as building the app or running tests. The `angular-seed`
 project contains a Travis configuration file, `.travis.yml`, which will cause Travis to run your
 tests when you push to GitHub.
 
-You will need to enable the integration between Travis and GitHub. See the Travis website for more
-instruction on how to do this.
-
+You will need to enable the integration between Travis and GitHub. See the
+[Travis website][travis-docs] for instructions on how to do this.
 
 
 ## Contact
 
-For more information on AngularJS please check out http://angularjs.org/
+For more information on AngularJS please check out [angularjs.org][angularjs].
+
 
-[bower]: http://bower.io
-[git]: http://git-scm.com/
-[http-server]: https://github.com/nodeapps/http-server
-[jasmine]: https://jasmine.github.io
-[jdk]: https://en.wikipedia.org/wiki/Java_Development_Kit
-[jdk-download]: http://www.oracle.com/technetwork/java/javase/downloads/index.html
-[karma]: https://karma-runner.github.io
-[node]: https://nodejs.org
+[angularjs]: https://angularjs.org/
+[bower]: http://bower.io/
+[git]: https://git-scm.com/
+[http-server]: https://github.com/indexzero/http-server
+[jasmine]: https://jasmine.github.io/
+[jdk]: https://wikipedia.org/wiki/Java_Development_Kit
+[jdk-download]: http://www.oracle.com/technetwork/java/javase/downloads
+[karma]: https://karma-runner.github.io/
+[local-app-url]: http://localhost:8000/index.html
+[node]: https://nodejs.org/
 [npm]: https://www.npmjs.org/
-[protractor]: https://github.com/angular/protractor
+[protractor]: http://www.protractortest.org/
 [selenium]: http://docs.seleniumhq.org/
 [travis]: https://travis-ci.org/
+[travis-docs]: https://docs.travis-ci.com/user/getting-started