docs(dynamic-forms): edit copy to guidelines standards (#3525)

Author: kapunahelewong

public/docs/ts/latest/cookbook/dynamic-form.jade

@@ -1,109 +1,115 @@
 include ../_util-fns
 
 :marked
-   We can't always justify the cost and time to build handcrafted forms, 
-   especially if we'll need a great number of them, they're similar to each other, and they change frequently 
+   Building handcrafted forms can be costly and time-consuming, 
+   especially if you need a great number of them, they're similar to each other, and they change frequently
    to meet rapidly changing business and regulatory requirements.
-   
-   It may be more economical to create the forms dynamically, based on metadata that describe the business object model.
-   
-   In this cookbook we show how to use `formGroup` to dynamically render a simple form with different control types and validation.
-   It's a primitive start. 
+
+   It may be more economical to create the forms dynamically, based on 
+   metadata that describes the business object model.
+
+   This cookbook shows you how to use `formGroup` to dynamically 
+   render a simple form with different control types and validation.
+   It's a primitive start.
    It might evolve to support a much richer variety of questions, more graceful rendering, and superior user experience.
    All such greatness has humble beginnings.
-  
-   In our example we use a dynamic form to build an online application experience for heroes seeking employment.
+
+   The example in this cookbook is a dynamic form to build an 
+   online application experience for heroes seeking employment.
    The agency is constantly tinkering with the application process.
-   We can create the forms on the fly *without changing our application code*. 
-   
+   You can create the forms on the fly *without changing the application code*.
+
 <a id="toc"></a>
 :marked
-   ## Table of contents
-
-      [Bootstrap](#bootstrap)
-
-      [Question Model](#object-model)
-
-      [Form Component](#form-component)
-
-      [Questionnaire Metadata](#questionnaire-metadata)
-      
-      [Dynamic Template](#dynamic-template)
+   # Contents
+    * [Bootstrap](#bootstrap)
+    * [Question model](#object-model)
+    * [Question form components](#form-component)
+    * [Questionnaire data](#questionnaire-data)
+    * [Dynamic template](#dynamic-template)
 
 :marked
-   **See the <live-example name="cb-dynamic-form"></live-example>**.
+   See the <live-example name="cb-dynamic-form"></live-example>.
 
 .l-main-section
 <a id="bootstrap"></a>
 :marked
    ## Bootstrap
 
-   We start by creating an `NgModule` called `AppModule`.
+   Start by creating an `NgModule` called `AppModule`.
 
-   In our example we will be using Reactive Forms. 
-   
-   Reactive Forms belongs to a different `NgModule` called `ReactiveFormsModule`, so in order to access any Reactive Forms directives, we have to import `ReactiveFormsModule` from the `@angular/forms` library.    
+   This cookbook uses [reactive forms](../guide/reactive-forms.html).
 
-   We bootstrap our `AppModule` in main.ts.
+   Reactive forms belongs to a different `NgModule` called `ReactiveFormsModule`, 
+   so in order to access any reactive forms directives, you have to import 
+   `ReactiveFormsModule` from the `@angular/forms` library.
+
+   Bootstrap the `AppModule` in `main.ts`.
 
 +makeTabs(
   `cb-dynamic-form/ts/src/app/app.module.ts,
    cb-dynamic-form/ts/src/main.ts`,
   null,
   `app.module.ts,
    main.ts`
-)  
+)
 
 .l-main-section
 <a id="object-model"></a>
 :marked
-   ## Question Model
+   ## Question model
 
    The next step is to define an object model that can describe all scenarios needed by the form functionality.
-   The hero application process involves a form with a lot of questions. 
-   The "question" is the most fundamental object in the model.
+   The hero application process involves a form with a lot of questions.
+   The _question_ is the most fundamental object in the model.
 
-   We have created `QuestionBase` as the most fundamental question class.
+   The following `QuestionBase` is a fundamental question class.
 
 +makeExample('cb-dynamic-form/ts/src/app/question-base.ts','','src/app/question-base.ts')
 
 :marked
-   From this base we derived two new classes in `TextboxQuestion` and `DropdownQuestion` that represent Textbox and Dropdown questions. 
-   The idea is that the form will be bound to specific question types and render the appropriate controls dynamically. 
-   
-   `TextboxQuestion` supports multiple html5 types like text, email, url etc via the `type` property.
+   From this base you can derive two new classes in `TextboxQuestion` and `DropdownQuestion` 
+   that represent textbox and dropdown questions.
+   The idea is that the form will be bound to specific question types and render the 
+   appropriate controls dynamically.
+
+   `TextboxQuestion` supports multiple HTML5 types such as text, email, and url 
+   via the `type` property.
 
 +makeExample('cb-dynamic-form/ts/src/app/question-textbox.ts',null,'src/app/question-textbox.ts')(format='.')
 
 :marked
    `DropdownQuestion` presents a list of choices in a select box.
-   
+
 +makeExample('cb-dynamic-form/ts/src/app/question-dropdown.ts',null,'src/app/question-dropdown.ts')(format='.')
 
 :marked
-   Next we have defined `QuestionControlService`, a simple service for transforming our questions to a `FormGroup`. 
-   In a nutshell, the form group consumes the metadata from the question model and allows us to specify default values and validation rules.
+   Next is `QuestionControlService`, a simple service for transforming the questions to a `FormGroup`.
+   In a nutshell, the form group consumes the metadata from the question model and 
+   allows you to specify default values and validation rules.
 
 +makeExample('cb-dynamic-form/ts/src/app/question-control.service.ts',null,'src/app/question-control.service.ts')(format='.')
 
 <a id="form-component"></a>
 :marked
    ## Question form components
-   Now that we have defined the complete model we are ready to create components to represent the dynamic form.
+   Now that you have defined the complete model you are ready 
+   to create components to represent the dynamic form.
 
 :marked
-  `DynamicFormComponent` is the entry point and the main container for the form. 
+  `DynamicFormComponent` is the entry point and the main container for the form.
 +makeTabs(
   `cb-dynamic-form/ts/src/app/dynamic-form.component.html,
    cb-dynamic-form/ts/src/app/dynamic-form.component.ts`,
   null,
   `dynamic-form.component.html,
    dynamic-form.component.ts`
-)  
+)
 :marked
-  It presents a list of questions, each question bound to a `<df-question>` component element.
+  It presents a list of questions, each bound to a `<df-question>` component element.
   The `<df-question>` tag matches the `DynamicFormQuestionComponent`,
-  the component responsible for rendering the details of each _individual_ question based on values in the data-bound question object.  
+  the component responsible for rendering the details of each _individual_ 
+  question based on values in the data-bound question object.
 
 +makeTabs(
   `cb-dynamic-form/ts/src/app/dynamic-form-question.component.html,
@@ -113,48 +119,53 @@ include ../_util-fns
    dynamic-form-question.component.ts`
 )
 :marked
-  Notice this component can present any type of question in our model. 
-  We only have two types of questions at this point but we can imagine many more.
+  Notice this component can present any type of question in your model.
+  You only have two types of questions at this point but you can imagine many more.
   The `ngSwitch` determines which type of question to display.
-  
-  In both components  we're relying on Angular's **formGroup** to connect the template HTML to the
+
+  In both components  you're relying on Angular's **formGroup** to connect the template HTML to the
   underlying control objects, populated from the question model with display and validation rules.
 
-  `formControlName` and `formGroup` are directives defined in `ReactiveFormsModule`. Our templates can access these directives directly since we imported `ReactiveFormsModule` from `AppModule`.  
+  `formControlName` and `formGroup` are directives defined in 
+  `ReactiveFormsModule`. The templates can access these directives 
+  directly since you imported `ReactiveFormsModule` from `AppModule`.
 
-<a id="questionnaire-metadata"></a>
+<a id="questionnaire-data"></a>
 :marked
    ## Questionnaire data
 :marked
-  `DynamicFormComponent` expects the list of questions in the form of an array bound to  `@Input() questions`.
+  `DynamicFormComponent` expects the list of questions in the form of an array bound to `@Input() questions`.
+
+   The set of questions you've defined for the job application is returned from the `QuestionService`.
+   In a real app you'd retrieve these questions from storage.
+
+   The key point is that you control the hero job application questions 
+   entirely through the objects returned from `QuestionService`.
+   Questionnaire maintenance is a simple matter of adding, updating, 
+   and removing objects from the `questions` array.
 
-   The set of questions we have defined for the job application is returned from the `QuestionService`. 
-   In a real app we'd retrieve these questions from storage.
-   
-   The key point is that we control the hero job application questions entirely through the objects returned from `QuestionService`. 
-   Questionnaire maintenance is a simple matter of adding, updating, and removing objects from the `questions` array.
-   
-+makeExample('cb-dynamic-form/ts/src/app/question.service.ts','','src/app/question.service.ts')  
++makeExample('cb-dynamic-form/ts/src/app/question.service.ts','','src/app/question.service.ts')
 
 :marked
-  Finally, we display an instance of the form in the `AppComponent` shell.
+  Finally, display an instance of the form in the `AppComponent` shell.
 
 +makeExample('cb-dynamic-form/ts/src/app/app.component.ts','','app.component.ts')
 
 <a id="dynamic-template"></a>
 :marked
    ## Dynamic Template
-   Although in this example we're modelling a job application for heroes, there are no references to any specific hero question 
-   outside the objects returned by `QuestionService`. 
-   
-   This is very important since it allows us to repurpose the components for any type of survey
-   as long as it's compatible with our *question* object model. 
-   The key is the dynamic data binding of metadata used to render the form 
-   without making any hardcoded assumptions about specific questions. 
-   In addition to control metadata, we are also adding validation dynamically.
-
-   The *Save* button is disabled until the form is in a valid state. 
-   When the form is valid, we can click *Save* and the app renders the current form values as JSON. 
+   Although in this example you're modelling a job application for heroes, there are 
+   no references to any specific hero question
+   outside the objects returned by `QuestionService`.
+
+   This is very important since it allows you to repurpose the components for any type of survey
+   as long as it's compatible with the *question* object model.
+   The key is the dynamic data binding of metadata used to render the form
+   without making any hardcoded assumptions about specific questions.
+   In addition to control metadata, you are also adding validation dynamically.
+
+   The *Save* button is disabled until the form is in a valid state.
+   When the form is valid, you can click *Save* and the app renders the current form values as JSON.
    This proves that any user input is bound back to the data model.
    Saving and retrieving the data is an exercise for another time.