docs(style-guide): copy edits

Author: kapunahelewong

public/docs/ts/latest/guide/style-guide.jade

@@ -63,7 +63,7 @@ a(id='toc')
 :marked
   ## Single Responsibility
 
-  Apply the [single responsibility principle](https://wikipedia.org/wiki/Single_responsibility_principle) to all components, services, and other symbols. 
+  Apply the [Single Responsibility Principle (SPR)](https://wikipedia.org/wiki/Single_responsibility_principle) to all components, services, and other symbols. 
   This helps make the app cleaner, easier to read and maintain, and more testable.
 
   ### <a id="01-01"></a>Rule of One
@@ -95,8 +95,8 @@ a(id='toc')
 
 +makeExample('style-guide/ts/01-01/app/heroes/hero.component.avoid.ts', '', 'app/heroes/hero.component.ts')(avoid=1)
 :marked
-  Redistributing the component and supporting activities into their own dedicated files 
-  is a better practice.
+  It is a better practice to redistribute the component and its 
+  supporting classes into their own, dedicated files.
 
 +makeTabs(
   `style-guide/ts/01-01/main.ts,
@@ -239,20 +239,25 @@ a(href="#toc") Back to top
 
 .s-rule.do
   :marked
-    **Do** match the name of the symbol to the name of the file. 
+    **Do** use upper camel case for class names.
 
 .s-rule.do
   :marked
-    **Do** append the symbol name with the conventional suffix for a thing of that type. 
-    For example, `Component`, `Directive`, `Module`, `Pipe`, `Service`.
+    **Do** match the name of the symbol to the name of the file.
 
 .s-rule.do
   :marked
-    **Do** give the filename the conventional suffix for a file of that type.
-    For example, `.component.ts`, `.directive.ts`, `.module.ts`, `.pipe.ts`, `.service.ts`.
+    **Do** append the symbol name with the conventional suffix (such as `Component`, 
+    `Directive`, `Module`, `Pipe`, or `Service`) for a thing of that type.
+
+.s-rule.do
+  :marked
+    **Do** give the filename the conventional suffix (such as `.component.ts`, `.directive.ts`, 
+    `.module.ts`, `.pipe.ts`, or `.service.ts`) for a file of that type.
 .s-why
   :marked
-    **Why?** Provides a conventional and consistent way to quickly identify and reference assets.
+    **Why?** Consistent conventions make it easy to quickly identify 
+    and reference assets of different types.
 
 - var top="vertical-align:top"
 table(width="100%")
@@ -340,7 +345,15 @@ a(href="#toc") Back to top
 
 .s-rule.do
   :marked
-    **Do** suffix services with `Service` when it is not clear what they are, such as when they are nouns.
+    **Do** suffix a service class name with Service. 
+    For example, something that gets data or heroes 
+    should be called a `DataService` or a `HeroService`.
+
+    A few terms are unambiguously services. They typically 
+    indicate agency by ending in "er". You may prefer to name 
+    a service that logs messages `Logger` rather than `LoggerService`. 
+    Decide if this exception is agreeable in your project. 
+    As always, strive for consistency.
 
 .s-why
   :marked
@@ -1106,7 +1119,7 @@ a(href="#toc") Back to top
 
 a(id='file-tree')
 :marked
-  Here is a compliant folder and file structure
+  Here is a compliant folder and file structure:
 
 .filetree
   .file &lt;project root&gt;
@@ -1183,7 +1196,7 @@ a(href="#toc") Back to top
 .s-why
   :marked
     **Why?** A developer can locate the code, identify what each file represents 
-    at a glance, the structure is as flat as it can be, and there are no repetitive nor redundant names.
+    at a glance, the structure is as flat as it can be, and there are no repetitive or redundant names.
 
 .s-why
   :marked
@@ -1210,7 +1223,7 @@ a(href="#toc") Back to top
     **Why?** Angular modules make it easier to isolate, test, and re-use features.
 
 .file-tree-reference
-  a(href="#file-tree") Refer to this Folder and File Structure example
+  a(href="#file-tree") Refer to this _folder and file structure_ example.
 
 a(href="#toc") Back to top
   :marked
@@ -1299,7 +1312,19 @@ a(href="#toc") Back to top
 
 .s-rule.do
   :marked
-    **Do** put common components, directives, and pipes that will be used throughout the application by other feature modules in the `SharedModule`, where those assets are expected to share a new instance of themselves (not singletons).
+    **Do** declare components, directives, and pipes in a shared module when those 
+    items will be re-used and referenced by the components declared in other feature modules.
+
+.s-rule.consider
+  :marked
+    **Consider** using the name SharedModule, when the contents of a shared 
+    module are referenced across the entire application.
+
+.s-rule.do
+  :marked
+    **Do** not provide services in shared modules. Services are usually 
+    singletons that are provided once for the entire application or 
+    in a particular feature module.
 
 .s-rule.do
   :marked
@@ -1378,9 +1403,16 @@ a(href="#toc") Back to top
   ### <a id="04-11"></a>Core Feature Module
   #### <a href="#04-11">Style 04-11</a>
 
-.s-rule.do
+.s-rule.consider
   :marked
-    **Do** collect single-use classes and hide their gory details inside `CoreModule`. A simplified root `AppModule` imports `CoreModule` in its capacity as orchestrator of the application as a whole.
+    **Consider** collecting numerous, auxiliary, single-use classes inside a core module
+    to simplify the apparent structure of a feature module.
+
+.s-rule.consider
+  :marked
+    **Consider** calling the application-wide core module, `CoreModule`.
+    Importing `CoreModule` into the root `AppModule` reduces its complexity 
+    and emphasizes its role as orchestrator of the application as a whole.
 
 .s-rule.do
   :marked
@@ -1988,8 +2020,9 @@ a(href="#toc") Back to top
 
 .s-why
   :marked
-    **Why?** When providing the service to a top level component, that instance is shared and available to all child components of that top level component.
-
+    **Why?** When providing the service to a top level component, 
+    that instance is shared and available to all child components of that top level component.
+    
 .s-why
   :marked
     **Why?** This is ideal when a service is sharing methods or state.
@@ -2019,8 +2052,8 @@ a(href="#toc") Back to top
 
 .s-why
   :marked
-    **Why?** The Angular Dependency Injection (DI) mechanism resolves all dependencies 
-    of services based on their types declared with the services' constructors.
+    **Why?** The Angular Dependency Injection (DI) mechanism resolves a service's own 
+    dependencies based on the declared types of that service's constructor parameters.
 
 .s-why.s-why-last
   :marked
@@ -2059,11 +2092,13 @@ a(href="#toc") Back to top
 
 .s-why.s-why-last
   :marked
-    **Why?** Data service implementation may have very specific code to handle the data repository. 
-    This may include headers, how to talk to the data, or other services such as `Http`. 
-    Separating the logic into a data service encapsulates this logic in a 
-    single place and hides the implementation from the outside consumers 
-    (perhaps a component). This also makes it easier to change the implementation.
+    **Why?** The details of data management, such as headers, HTTP methods, 
+    caching, error handling, and retry logic, are irrelevant to components 
+    and other data consumers.
+
+    A data service encapsulates these details. It's easier to evolve these 
+    details inside the service without affecting its consumers. And it's 
+    easier to test the consumers with mock service implementations.
 
 a(href="#toc") Back to top
 
@@ -2086,8 +2121,8 @@ a(href="#toc") Back to top
 
 .s-why.s-why-last
   :marked
-    **Why?** Lifecycle hook interfaces use strongly-typed method signatures.
-    The compiler and editor can call out misspellings.
+    **Why?** Lifecycle interfaces prescribe typed method 
+    signatures. use those signatures to flag spelling and syntax mistakes.
 
 +makeExample('style-guide/ts/09-01/app/heroes/shared/hero-button/hero-button.component.avoid.ts', 'example', 'app/heroes/shared/hero-button/hero-button.component.ts')(avoid=1)
 :marked