Update README.md

Author: Rick Anderson

README.md

@@ -6,7 +6,11 @@ This project is part of ASP.NET Core. You can find samples, documentation and ge
 
 ## What is this?
 
-`JavaScriptServices` is a set of technologies for ASP.NET Core developers. It provides infrastructure that you'll find useful if you use Angular 2 / React / Knockout / etc. on the client, or if you build your client-side resources using Webpack, or otherwise want to execute JavaScript on the server at runtime.
+`JavaScriptServices` is a set of client-side technologies for ASP.NET Core. It provides infrastructure that you'll find useful if you:
+
+-  Use Angular 2 / React / Knockout / etc. <!-- do we need on the client? -->
+-  Build your client-side resources using Webpack.
+-  Execute JavaScript on the server at runtime.
 
 This repo contains:
 
@@ -22,22 +26,22 @@ This repo contains:
  * A Yeoman generator that creates preconfigured app starting points ([guide](http://blog.stevensanderson.com/2016/05/02/angular2-react-knockout-apps-on-aspnet-core/))
  * Samples and docs
 
-Everything here is cross-platform, and works with .NET Core 1.0.1 or later on Windows, Linux, or OS X.
+It's cross-platform (Windows, Linux, or macOS) and works with .NET Core 1.0.1 or later.
 
 ## Creating new applications
 
-If you want to build a brand-new ASP.NET Core app that uses Angular 2 / React / Knockout on the client, consider starting with the `aspnetcore-spa` generator. This lets you choose your client-side framework, and generates a starting point that includes applicable features such as Webpack dev middleware, server-side prerendering, and efficient production builds. It's much easier than configuring everything to work together manually!
+If you want to build a brand-new ASP.NET Core app that uses Angular 2 / React / Knockout on the client, consider starting with the `aspnetcore-spa` generator. This lets you choose your client-side framework. It generates a starting point that includes applicable features such as Webpack dev middleware, server-side prerendering, and efficient production builds. It's much easier than configuring everything to work together manually!
 
-To do this, first install Yeoman and these generator templates:
+To do this, install Yeoman and these generator templates:
 
     npm install -g yo generator-aspnetcore-spa
 
-Then you can generate your new application starting point:
+Generate your new application starting point:
 
     cd some-empty-directory
     yo aspnetcore-spa
 
-Finally, once the generator has run and restored all the dependencies, you can start up your new ASP.NET Core Single Page Application:
+Once the generator has run and restored all the dependencies, you can start up your new ASP.NET Core SPA:
 
     dotnet run 
 
@@ -56,23 +60,26 @@ If you have an existing ASP.NET Core application, or if you just want to use the
    * Find [documentation and usage examples here](https://github.com/aspnet/JavaScriptServices/tree/dev/src/Microsoft.AspNetCore.SpaServices#microsoftaspnetcorespaservices).
  * `Microsoft.AspNetCore.AngularServices`
    * This builds on the `SpaServices` package and includes features specific to Angular 2. Currently, this includes validation helpers and a "cache priming" feature, which let you pre-evaluate ajax requests on the server so that client-side code doesn't need to make network calls once it's loaded.
-   * The code is [here](https://github.com/aspnet/JavaScriptServices/tree/dev/src/Microsoft.AspNetCore.AngularServices), and you'll find a usage example for [the validation helper here](https://github.com/aspnet/JavaScriptServices/blob/dev/samples/angular/MusicStore/wwwroot/ng-app/components/admin/album-edit/album-edit.ts), and for the [cache priming here](https://github.com/aspnet/JavaScriptServices/blob/dev/samples/angular/MusicStore/Views/Home/Index.cshtml#L7-8). Full docs are to be written.
+   * The code is [here](https://github.com/aspnet/JavaScriptServices/tree/dev/src/Microsoft.AspNetCore.AngularServices), and you'll find a usage example for [the validation helper here](https://github.com/aspnet/JavaScriptServices/blob/dev/samples/angular/MusicStore/wwwroot/ng-app/components/admin/album-edit/album-edit.ts), and for the [cache priming here](https://github.com/aspnet/JavaScriptServices/blob/dev/samples/angular/MusicStore/Views/Home/Index.cshtml#L7-8). Complete documentation is planned. <!-- can we link to an issue? -->
 
 There was previously a `Microsoft.AspNetCore.ReactServices` but this is not currently needed - all applicable functionality is in `Microsoft.AspNetCore.SpaServices`, because it's sufficiently general. We might add a new `Microsoft.AspNetCore.ReactServices` package in the future if new React-specific requirements emerge.
 
 If you want to build a helper library for some other SPA framework, you can do so by taking a dependency on `Microsoft.AspNetCore.SpaServices` and wrapping its functionality in whatever way is most useful for your SPA framework.
 
 ## Samples and templates
 
-Inside this repo, [the `templates` directory](https://github.com/aspnet/JavaScriptServices/tree/dev/templates) contains the application starting points that the `aspnetcore-spa` generator emits. If you want, you can clone this repo and run those applications directly. But it's easier to [use the Yeoman tool to run the generator](http://blog.stevensanderson.com/2016/05/02/angular2-react-knockout-apps-on-aspnet-core/).
+Inside this repo, [the `templates` directory](https://github.com/aspnet/JavaScriptServices/tree/dev/templates) contains the application starting points that the `aspnetcore-spa` generator emits. You can clone this repo and run those applications directly. But it's easier to [use the Yeoman tool to run the generator](http://blog.stevensanderson.com/2016/05/02/angular2-react-knockout-apps-on-aspnet-core/).
+
+The [ `samples` directory](https://github.com/aspnet/JavaScriptServices/tree/dev/samples) contains examples of:
 
-Also in this repo, [the `samples` directory](https://github.com/aspnet/JavaScriptServices/tree/dev/samples) contains examples of using the JavaScript services family of packages with Angular 2 and React, plus examples of standalone `NodeServices` usage for runtime code transpilation and image processing.
+- Using the JavaScript services family of packages with Angular 2 and React.
+- A standalone `NodeServices` usage for runtime code transpilation and image processing.
 
 **To run the samples:**
 
  * Clone this repo
  * At the repo's root directory (the one containing `src`, `samples`, etc.), run `dotnet restore`
- * Change directory to the sample you want to run (e.g., `cd samples/angular/MusicStore`)
+ * Change directory to the sample you want to run (for example, `cd samples/angular/MusicStore`)
  * Restore Node dependencies by running `npm install`
    * If you're trying to run the Angular 2 "Music Store" sample, then also run `gulp` (which you need to have installed globally). None of the other samples require this.
  * Run the application (`dotnet run`)
@@ -84,8 +91,8 @@ If you're interested in contributing to the various packages, samples, and proje
 
  * Cloning the repo
  * Running `dotnet restore` at the repo root dir
- * Going to whatever sample or template you want to run (e.g., `cd templates/Angular2Spa`)
+ * Going to whatever sample or template you want to run (for example, `cd templates/Angular2Spa`)
  * Restoring NPM dependencies (run `npm install`)
  * Launching it (`dotnet run`)
 
-If you're planning to submit a pull request, and if it's more than a trivial fix (e.g., for a typo), it's usually a good idea first to file an issue describing what you're proposing to do and how it will work. Then you can find out if it's likely that such a pull request will be accepted, and how it fits into wider ongoing plans.
+If you're planning to submit a pull request, and if it's more than a trivial fix (for example, for a typo), it's usually a good idea first to file an issue describing what you're proposing to do and how it will work. Then you can find out if it's likely that such a pull request will be accepted, and how it fits into wider ongoing plans.