guide WIP [skip ci]

docs/guide/README.md

@@ -121,7 +121,7 @@ Caching
 RESTful Web Services
 --------------------
 
-* [Quick Start](rest-quick-start.md)
+* [A Quick Start](rest-quick-start.md)
 * [Resources](rest-resources.md)
 * [Controllers](rest-controllers.md)
 * [Routing](rest-routing.md)

docs/guide/rest-quick-start.md

-Quick Start
-===========
+A Quick Start
+=============
 
 Yii provides a whole set of tools to simplify the task of implementing RESTful Web Service APIs.
-In particular, Yii provides support for the following aspects regarding RESTful APIs:
+In particular, Yii supports the following features about RESTful APIs:
 
 * Quick prototyping with support for common APIs for [Active Record](db-active-record.md);
 * Response format (supporting JSON and XML by default) negotiation;
@@ -16,7 +16,8 @@ In particular, Yii provides support for the following aspects regarding RESTful
 * Rate limiting;
 
 
-Let's use a quick example to show how to build a set of RESTful APIs using Yii.
+In the following, we use an example to illustrate how you can build a set of RESTful APIs with some minimal coding effort.
+
 Assume you want to expose the user data via RESTful APIs. The user data are stored in the user DB table,
 and you have already created the [[yii\db\ActiveRecord|ActiveRecord]] class `app\models\User` to access the user data.
 
@@ -37,6 +38,9 @@ class UserController extends ActiveController
 }
 ```
 
+The controller class extends from [[yii\rest\ActiveController]]. By specifying [[yii\rest\ActiveController::modelClass|modelClass]]
+as `app\models\User`, the controller knows what model can be used for fetching and manipulating data.
+
 
 Configuring URL Rules
 ---------------------
@@ -54,7 +58,11 @@ Then, modify the configuration about the `urlManager` component in your applicat
 ]
 ```
 
-Trying it Out
+The above configuration mainly adds a URL rule for the `user` controller so that the user data
+can be accessed and manipulated with pretty URLs and meaningful HTTP verbs.
+
+
+Trying it Out <a name="trying-it-out"></a>
 -------------
 
 With the above minimal amount of effort, you have already finished your task of creating the RESTful APIs
@@ -159,10 +167,11 @@ Using the Yii RESTful API framework, you implement an API endpoint in terms of a
 a controller to organize the actions that implement the endpoints for a single type of resource.
 
 Resources are represented as data models which extend from the [[yii\base\Model]] class.
-If you are working with databases (relational or NoSQL), it is recommended you use ActiveRecord to represent resources.
+If you are working with databases (relational or NoSQL), it is recommended you use [[yii\db\ActiveRecord|ActiveRecord]]
+to represent resources.
 
 You may use [[yii\rest\UrlRule]] to simplify the routing to your API endpoints.
 
-While not required, it is recommended that you develop your RESTful APIs as an application, separated from
-your Web front end and back end.
+While not required, it is recommended that you develop your RESTful APIs as a separate application, different from
+your Web front end and back end for easier maintenance.
 

docs/guide/start-databases.md

@@ -216,8 +216,8 @@ The `LinkPager` widget displays a list of page buttons. Clicking on any of them
 in the corresponding page.
 
 
-How It Works <a name="how-it-works"></a>
-------------
+Trying it Out <a name="trying-it-out"></a>
+-------------
 
 To see how it works, use your browser to access the following URL:
 

docs/guide/start-forms.md

@@ -160,8 +160,8 @@ and the second the "email" data. After the input fields, the [[yii\helpers\Html:
 is called to generate a submit button.
 
 
-How It Works <a name="how-it-works"></a>
-------------
+Trying it Out <a name="trying-it-out"></a>
+-------------
 
 To see how it works, use your browser to access the following URL:
 

docs/guide/start-gii.md

@@ -90,8 +90,8 @@ Make sure you have checked the overwrite checkboxes for both `controllers/Countr
 in the previous section and you want to have them overwritten to have full CRUD support.
 
 
-How It Works <a name="how-it-works"></a>
-------------
+Trying it Out <a name="trying-it-out"></a>
+-------------
 
 To see how it works, use your browser to access the following URL:
 

docs/guide/start-hello.md

@@ -93,8 +93,8 @@ In fact, the `say` view is just a PHP script which is executed by the [[yii\web\
 The content echoed by the view script will be forwarded by the application as the response to the end user.
 
 
-How It Works <a name="how-it-works"></a>
-------------
+Trying it Out <a name="trying-it-out"></a>
+-------------
 
 After creating the action and the view, you may access the new page by the following URL:
 

docs/guide/start-workflow.md

@@ -11,7 +11,7 @@ and how the application handles requests in general.
   Please adjust the URLs accordingly in our descriptions.
 
 
-Functionalities
+Functionalities <a name="functionalities"></a>
 ---------------
 
 The application that you have installed contains four pages:
@@ -30,7 +30,7 @@ This is a useful [debugger tool](tool-debugger.md) provided by Yii to help you c
 about the application execution, such as log messages, response status, database queries, and so on.
 
 
-Application Structure
+Application Structure <a name="application-structure"></a>
 ---------------------
 
 The following is a list of the most important directories and files in your application,
@@ -72,7 +72,7 @@ and dispatches the request to MVC. [Widgets](structure-widgets.md) are used in t
 to help build complex and dynamic user interface elements.
 
 
-Request Lifecycle
+Request Lifecycle <a name="request-lifecycle"></a>
 -----------------
 
 The following diagram shows how an application handles a request.