diff --git a/docs/guide/start-forms.md b/docs/guide/start-forms.md
index 34de19c7d5..6c2c4f90eb 100644
--- a/docs/guide/start-forms.md
+++ b/docs/guide/start-forms.md
@@ -1,25 +1,25 @@
Working with Forms
==================
-In this section, we will describe how to create a new page to get data from users.
+This section describes how to create a new page with a form for getting data from users.
The page will display a form with a name input field and an email input field.
-After getting these data from a user, the page will echo them back to the user for confirmation.
+After getting those two pieces of information from the user, the page will echo the entered values back for confirmation.
To achieve this goal, besides creating an [action](structure-controllers.md) and
two [views](structure-views.md), you will also create a [model](structure-models.md).
-Through this tutorial, you will learn
+Through this tutorial, you will learn how to:
-* How to create a [model](structure-models.md) to represent the data entered by a user;
-* How to declare rules to validate the data entered by users;
-* How to build an HTML form in a [view](structure-views.md).
+* Create a [model](structure-models.md) to represent the data entered by a user through a form
+* Declare rules to validate the data entered
+* Build an HTML form in a [view](structure-views.md)
Creating a Model
----------------
-To represent the data entered by a user, create an `EntryForm` model class as shown below and
-save the class in the file `models/EntryForm.php`. Please refer to the [Class Autoloading](concept-autoloading.md)
+The data to be requested from the user will be represented by an `EntryForm` model class as shown below and
+saved in the file `models/EntryForm.php`. Please refer to the [Class Autoloading](concept-autoloading.md)
section for more details about the class file naming convention.
```php
@@ -44,26 +44,38 @@ class EntryForm extends Model
}
```
-The class extends from [[yii\base\Model]], a base class provided by Yii that is commonly used to
+The class extends from [[yii\base\Model]], a base class provided by Yii, commonly used to
represent form data.
-The class contains two public members, `name` and `email`, which are used to keep
-the data entered by the user. It also contains a method named `rules()` which returns a set
-of rules used for validating the data. The validation rules declared above state that
+> Info: [[yii\base\Model]] is used as a parent for model classes *not* associated with database tables. [[yii\db\ActiveRecord]] is normally the parent for model classes that do correspond to database tables.
-* both the `name` and `email` data are required;
-* the `email` data must be a valid email address.
+The `EntryForm` class contains two public members, `name` and `email`, which are used to store
+the data entered by the user. It also contains a method named `rules()`, which returns a set
+of rules for validating the data. The validation rules declared above state that
+
+* both the `name` and `email` values are required
+* the `email` data must be a syntactically valid email address
If you have an `EntryForm` object populated with the data entered by a user, you may call
-its [[yii\base\Model::validate()|validate()]] to trigger the data validation. A data validation
-failure will turn on the [[yii\base\Model::hasErrors|hasErrors]] property, and through
-[[yii\base\Model::getErrors|errors]] you may learn what validation errors the model has.
+its [[yii\base\Model::validate()|validate()]] to trigger the data validation routines. A data validation
+failure will set the [[yii\base\Model::hasErrors|hasErrors]] property to true, and you may learn what validation errors occurred through [[yii\base\Model::getErrors|errors]].
+
+```php
+name = 'Qiang';
+$model->email = 'bad';
+if ($model->validate()) { // Good!
+} else { // Failure!
+ // Use $model->getErrors()
+}
+```
Creating an Action
------------------
-Next, create an `entry` action in the `site` controller, like you did in the previous section.
+Next, you'll need to create an `entry` action in the `site` controller that will use the new model. The process of creating and using actions was explained in the [Saying Hello](start-hello.md) section.
```php
Info: The expression `Yii::$app` represents the [application](structure-applications.md) instance
- which is a globally accessible singleton. It is also a [service locator](concept-service-locator.md)
- providing components, such as `request`, `response`, `db`, etc. to support specific functionalities.
- In the above code, the `request` component is used to access the `$_POST` data.
+> Info: The expression `Yii::$app` represents the [application](structure-applications.md) instance,
+ which is a globally accessible singleton. It is also a [service locator](concept-service-locator.md) that
+ provides components such as `request`, `response`, `db`, etc. to support specific functionality.
+ In the above code, the `request` component of the application instance is used to access the `$_POST` data.
Creating Views
--------------
-Finally, create two views named `entry-confirm` and `entry` that are rendered by the `entry` action,
-as described in the last subsection.
+Finally, create two view files named `entry-confirm` and `entry`. These will be rendered by the `entry` action,
+as just described.
-The `entry-confirm` view simply displays the name and email data. It should be stored as the file `views/site/entry-confirm.php`.
+The `entry-confirm` view simply displays the name and email data. It should be stored in the file `views/site/entry-confirm.php`.
```php
```
-The `entry` view displays an HTML form. It should be stored as the file `views/site/entry.php`.
+The `entry` view displays an HTML form. It should be stored in the file `views/site/entry.php`.
```php
Warning: Client-side validation is a conveniences that provides for a better user experience. Server-side validation is always required, whether or not client-side validation is in place.
+
+The labels for input fields are generated by the `field()` method, using the property names from the model.
+For example, the label `Name` will be generated for the `name` property.
+
+You may customize a label within a view using
the following code:
```php
@@ -205,18 +217,18 @@ the following code:
```
> Info: Yii provides many such widgets to help you quickly build complex and dynamic views.
- As you will learn later, writing a new widget is also extremely easy. You may turn much of your
+ As you will learn later, writing a new widget is also extremely easy. You may want to turn much of your
view code into reusable widgets to simplify view development in future.
Summary
-------
-In this section, you have touched every part in the MVC design pattern. You have learned how
-to create a model class to represent the user data and validate them.
+In this section of the guide, you have touched every part in the MVC design pattern. You have learned how
+to create a model class to represent the user data and validate said data.
-You have also learned how to get data from users and how to display them back. This is a task that
-could take you a lot of time when developing an application. Yii provides powerful widgets
+You have also learned how to get data from users and how to display data back in the browser. This is a task that
+could take you a lot of time when developing an application, but Yii provides powerful widgets
to make this task very easy.
-In the next section, you will learn how to work with databases which are needed in nearly every application.
+In the next section, you will learn how to work with databases, which are needed in nearly every application.