docs(style-guide): edit copy

Author: kapunahelewong

public/docs/_examples/style-guide/ts/05-14/app/shared/toast/toast.component.avoid.ts

@@ -7,7 +7,7 @@ export class ToastComponent implements OnInit {
 
   private defaults = {
     title: '',
-    message: 'May the Force be with You'
+    message: 'May the Force be with you'
   };
   message: string;
   title: string;

public/docs/_examples/style-guide/ts/05-14/app/shared/toast/toast.component.ts

@@ -14,7 +14,7 @@ export class ToastComponent implements OnInit {
   // private fields
   private defaults = {
     title: '',
-    message: 'May the Force be with You'
+    message: 'May the Force be with you'
   };
   private toastElement: any;
 

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

@@ -37,7 +37,8 @@ include ../_util-fns
 :marked
   ## File Structure Conventions
 
-  Some code examples display a file that has one or more similarly named companion files. (e.g. hero.component.ts and hero.component.html).
+  Some code examples display a file that has one or more similarly named companion files. 
+  For example, `hero.component.ts` and `hero.component.html`.
 
   The guideline will use the shortcut `hero.component.ts|html|css|spec` to represent those various files. Using this shortcut makes this guide's file structures easier to read and more terse.
 
@@ -47,53 +48,55 @@ a(id='toc')
 :marked
   ## Table of Contents
 
-    1. [Single Responsibility](#single-responsibility)
+    1. [Single responsibility](#single-responsibility)
     1. [Naming](#naming)
-    1. [Coding Conventions](#coding-conventions)
-    1. [App Structure and Angular Modules](#app-structure-and-angular-modules)
+    1. [Coding conventions](#coding-conventions)
+    1. [App structure and Angular modules](#app-structure-and-angular-modules)
     1. [Components](#components)
     1. [Directives](#directives)
     1. [Services](#services)
-    1. [Data Services](#data-services)
-    1. [Lifecycle Hooks](#lifecycle-hooks)
+    1. [Data services](#data-services)
+    1. [Lifecycle hooks](#lifecycle-hooks)
     1. [Appendix](#appendix)
 
 .l-main-section
 :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](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
   #### <a href="#01-01">Style 01-01</a>
 .s-rule.do
   :marked
-    **Do** define one thing (e.g. service or component) per file.
+    **Do** define one thing, such as a service or component, per file.
 
 .s-rule.consider
   :marked
     **Consider** limiting files to 400 lines of code.
 
 .s-why
   :marked
-    **Why?** One component per file makes it far easier to read, maintain, and avoid collisions with teams in source control.
+    **Why?** One component per file makes it far easier to read, maintain, and avoid 
+    collisions with teams in source control.
 
 .s-why
   :marked
     **Why?** One component per file avoids hidden bugs that often arise when combining components in a file where they may share variables, create unwanted closures, or unwanted coupling with dependencies.
 
 .s-why.s-why-last
   :marked
-    **Why?** A single component can be the default export for its file which facilitates lazy loading with the Router.
+    **Why?** A single component can be the default export for its file which facilitates lazy loading with the router.
 :marked
   The key is to make the code more reusable, easier to read, and less mistake prone.
 
   The following *negative* example defines the `AppComponent`, bootstraps the app, defines the `Hero` model object, and loads heroes from the server ... all in the same file. *Don't do this*.
 
 +makeExample('style-guide/ts/01-01/app/heroes/hero.component.avoid.ts', '', 'app/heroes/hero.component.ts')(avoid=1)
 :marked
-  Better to redistribute the component and supporting activities into their own dedicated files.
+  Redistributing the component and supporting activities into their own dedicated files 
+  is a better practice.
 
 +makeTabs(
   `style-guide/ts/01-01/main.ts,
@@ -203,7 +206,7 @@ a(href="#toc") Back to top
 
 .s-rule.do
   :marked
-    **Do** use conventional type names including `.service`, `.component`, `.pipe`, `.module`, `.directive`. 
+    **Do** use conventional type names including `.service`, `.component`, `.pipe`, `.module`, and `.directive`. 
     Invent additional type names if you must but take care not to create too many.
 
 .s-why
@@ -212,7 +215,7 @@ a(href="#toc") Back to top
 
 .s-why
   :marked
-    **Why?** Make it easy to find a specific file type using an editor or IDE's fuzzy search techniques.
+    **Why?** Type names make it easy to find a specific file type using an editor or IDE's fuzzy search techniques.
 
 .s-why
   :marked
@@ -221,7 +224,7 @@ a(href="#toc") Back to top
 
 .s-why.s-why-last
   :marked
-    **Why?** Provides pattern matching for any automated tasks.
+    **Why?** Type names provide pattern matching for any automated tasks.
 
 a(href="#toc") Back to top
 
@@ -236,24 +239,20 @@ a(href="#toc") Back to top
 
 .s-rule.do
   :marked
-    **Do** use upper camel case for class names. Match the name of the symbol to the name of the file.
+    **Do** match the name of the symbol to the name of the file. 
 
 .s-rule.do
   :marked
-    **Do** append the symbol name with the conventional suffix for a thing of that type 
-    (e.g., `Component`, `Directive`, `Module`, `Pipe`, `Service`).
+    **Do** append the symbol name with the conventional suffix for a thing of that type. 
+    For example, `Component`, `Directive`, `Module`, `Pipe`, `Service`.
 
 .s-rule.do
   :marked
-    **Do** give the filename the conventional suffix for a file of that type 
-    (e.g., `.component.ts`, `.directive.ts`, `.module.ts`, `.pipe.ts`, `.service.ts`).
+    **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`.
 .s-why
   :marked
-    **Why?** Provides a consistent way to quickly identify and reference assets.
-
-.s-why.s-why-last
-  :marked
-    **Why?** Upper camel case is conventional for identifying objects that can be instantiated using a constructor.
+    **Why?** Provides a conventional and consistent way to quickly identify and reference assets.
 
 - var top="vertical-align:top"
 table(width="100%")
@@ -341,11 +340,7 @@ a(href="#toc") Back to top
 
 .s-rule.do
   :marked
-    **Do** use upper camel case for services.
-
-.s-rule.do
-  :marked
-    **Do** suffix services with `Service` when it is not clear what they are (e.g. when they are nouns).
+    **Do** suffix services with `Service` when it is not clear what they are, such as when they are nouns.
 
 .s-why
   :marked
@@ -409,7 +404,7 @@ a(href="#toc") Back to top
 
 .s-rule.avoid
   :marked
-    **Avoid** putting app logic in the `main.ts`. Instead consider placing it in a component or service.
+    **Avoid** putting app logic in the `main.ts`. Instead, consider placing it in a component or service.
 
 .s-why
   :marked
@@ -805,7 +800,7 @@ a(href="#toc") Back to top
 
 .s-why
   :marked
-    **Why?** lower camel case variable names (`heroRoutes`) are easier to read and understand
+    **Why?** Lower camel case variable names (`heroRoutes`) are easier to read and understand
     than the traditional UPPER_SNAKE_CASE names (`HERO_ROUTES`).
 
 .s-why.s-why-last
@@ -822,7 +817,7 @@ a(href="#toc") Back to top
   :marked
     **Why?** The tradition of UPPER_SNAKE_CASE remains popular and pervasive,
     especially in third party modules.
-    It is rarely worth the effort to change them or the risk of breaking existing code and documentation.
+    It is rarely worth the effort to change them at the risk of breaking existing code and documentation.
 
 +makeExample('style-guide/ts/03-02/app/core/data.service.ts', '', 'app/shared/data.service.ts')
 :marked
@@ -849,7 +844,7 @@ a(href="#toc") Back to top
 .s-why
   :marked
     **Why?** <a href="https://github.com/Microsoft/TypeScript/wiki/Coding-guidelines" target="_blank">TypeScript guidelines</a> 
-    discourage the "I" prefix.
+    discourage the `I` prefix.
 
 .s-why
   :marked
@@ -946,9 +941,9 @@ a(href="#toc") Back to top
   All of the app's code goes in a folder named `app`. 
   All feature areas are in their own folder, with their own Angular module. 
 
-  All content is 1 asset per file. Each component, service, and pipe is in its own file. 
-  All 3rd party vendor scripts are stored in another folder and not in the `app` folder. 
-  You didn't write them and you don't want them cluttering app. 
+  All content is one asset per file. Each component, service, and pipe is in its own file. 
+  All third party vendor scripts are stored in another folder and not in the `app` folder. 
+  You didn't write them and you don't want them cluttering `app`. 
   Use the naming conventions for files in this guide.
 
 a(href="#toc") Back to top
@@ -1043,11 +1038,11 @@ a(href="#toc") Back to top
   :marked
     **Consider** configuring the IDE to hide distracting, irrelevant files such as generated `.js` and `.js.map` files.
 
-s-why.s-why-last
+.s-why.s-why-last
   :marked
     **Why?** No one wants to search for a file through seven levels of folders. 
     A flat structure is easy to scan.
-    
+
     On the other hand,
     <a href="https://en.wikipedia.org/wiki/The_Magical_Number_Seven,_Plus_or_Minus_Two" target="_blank">psychologists believe</a>
     that humans start to struggle when the number of adjacent interesting things exceeds nine.
@@ -1099,7 +1094,7 @@ a(href="#toc") Back to top
 
 .s-rule.consider
   :marked
-    **Consider** creating a folder for a component when is has multiple accompanying files (`.ts`, `.html`, `.css` and `.spec`).
+    **Consider** creating a folder for a component when it has multiple accompanying files (`.ts`, `.html`, `.css` and `.spec`).
 
 .s-why
   :marked
@@ -1169,7 +1164,7 @@ a(id='file-tree')
 
 .l-sub-section
   :marked
-    While components in dedicated folder are widely preferred, 
+    While components in dedicated folders are widely preferred, 
     another option for small apps is to keep components flat (not in a dedicated folder). 
     This adds up to four files to the existing folder, but also reduces the folder nesting. 
     Whatever you choose, be consistent.
@@ -1187,7 +1182,8 @@ 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 is no repetitive nor redundant names.
+    **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.
 
 .s-why
   :marked
@@ -1214,7 +1210,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 here 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
@@ -1303,7 +1299,7 @@ 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** 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).
 
 .s-rule.do
   :marked
@@ -1384,7 +1380,7 @@ a(href="#toc") Back to top
 
 .s-rule.do
   :marked
-    **Do** collect single-use classes and hiding their gory details inside `CoreModule`. A simplified root `AppModule` imports `CoreModule` in its capacity as orchestrator of the application as a whole.
+    **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.
 
 .s-rule.do
   :marked
@@ -1431,7 +1427,7 @@ a(href="#toc") Back to top
 
 .s-rule.do
   :marked
-    **Do** export all symbols that from the `CoreModule` that the `AppModule` will import and make available for other feature modules to use.  
+    **Do** export all symbols from the `CoreModule` that the `AppModule` will import and make available for other feature modules to use.  
 
 .s-why
   :marked
@@ -1692,7 +1688,7 @@ a(href="#toc") Back to top
 .s-why
   :marked
     **Why?** If you ever need to rename the property or event name associated with 
-    `@Input` or `@Output`, you can modify it a single place.
+    `@Input` or `@Output`, you can modify it in a single place.
 
 .s-why
   :marked
@@ -1721,7 +1717,8 @@ a(href="#toc") Back to top
 
 .s-why.s-why-last
   :marked
-    **Why?** May lead to confusion when the output or the input properties of a given directive are named a given way but exported differently as a public API.
+    **Why?** May lead to confusion when the output or the input 
+    properties of a given directive are named one way but exported differently as a public API.
 
 +makeExample('style-guide/ts/05-13/app/heroes/shared/hero-button/hero-button.component.avoid.ts', 'example', 'app/heroes/shared/hero-button/hero-button.component.ts')(avoid=1)
 :marked
@@ -2022,7 +2019,8 @@ a(href="#toc") Back to top
 
 .s-why
   :marked
-    **Why?** The Angular DI mechanism resolves all dependencies of services based on their types declared with the services' constructors.
+    **Why?** The Angular Dependency Injection (DI) mechanism resolves all dependencies 
+    of services based on their types declared with the services' constructors.
 
 .s-why.s-why-last
   :marked
@@ -2061,7 +2059,11 @@ 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 hiding the implementation from the outside consumers (perhaps a component), also making it easier to change the implementation.
+    **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.
 
 a(href="#toc") Back to top
 
@@ -2084,7 +2086,7 @@ a(href="#toc") Back to top
 
 .s-why.s-why-last
   :marked
-    **Why?** Strongly-typed method signatures.
+    **Why?** Lifecycle hook interfaces use strongly-typed method signatures.
     The compiler and editor can call out misspellings.
 
 +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)