fixup! apply feedback

docs/site/HasMany-relation.md

@@ -103,9 +103,9 @@ repository, the following are required:
   `HasManyRepositoryFactory<targetModel, typeof sourceModel.prototype.id>` on
   the source repository class.
 - call the `_createHasManyRepositoryFactoryFor` function in the constructor of
-  the source repository class with the relation name (decorated relation propert
-  on the source model) and target repository instance and assign it the property
-  mentioned above.
+  the source repository class with the relation name (decorated relation
+  property on the source model) and target repository instance and assign it the
+  property mentioned above.
 
 The following code snippet shows how it would look like:
 
@@ -163,7 +163,7 @@ underlying constrained repository CRUD APIs and expose them as routes once
 decorated with
 [Route decorators](Routes.md#using-route-decorators-with-controller-methods). It
 will require the value of the foreign key and, depending on the request method,
-a partial value for the target model instance as demonstrated below.
+a value for the target model instance as demonstrated below.
 
 {% include code-caption.html
 content="src/controllers/customer-orders.controller.ts" %}
@@ -180,7 +180,7 @@ export class CustomerOrdersController {
   ) {}
 
   @post('/customers/{id}/order')
-  async createCustomerOrders(
+  async createOrder(
     @param.path.number('id') customerId: typeof Customer.prototype.id,
     @requestBody() orderData: Order,
   ): Promise<Order> {
@@ -189,4 +189,18 @@ export class CustomerOrdersController {
 }
 ```
 
-<!--- TODO: Add details about `orderData` variable typing issue --->
+In LoopBack 3, methods for accessing related models were part of the source
+model class i.e. `customer.orders.find(...)`. We recommend to create new
+controller for each relation in LoopBack 4 for two reasons. First, it keeps
+controller classes smaller. Second, it creates a logical separation of ordinary
+repositories and relational repositories and thus the controllers which use
+them. Therefore, as shown above, don't add order-related methods to
+`CustomerController`, but instead create a new `CustomerOrdersController` class
+for them.
+
+{% include note.html content="
+The type of `orderData` above will possibly change to `Partial<Order>` exclude
+certain properties from the JSON/OpenAPI spec schema built for the `requestBody`
+payload. See its [GitHub
+issue](https://github.com/strongloop/loopback-next/issues/1179) to follow the discussion.
+" %}

docs/site/Relations.md

@@ -10,6 +10,21 @@ summary:
 
 ## Overview
 
+Individual models are easy to understand and work with. But in reality, models
+are often connected or related. When you build a real-world application with
+multiple models, you’ll typically need to define relations between models. For
+example:
+
+- A customer has many orders and each order is owned by a customer.
+- A user can be assigned to one or more roles and a role can have zero or more
+  users.
+- A physician takes care of many patients through appointments. A patient can
+  see many physicians too.
+
+With connected models, LoopBack exposes as a set of APIs to interact with each
+of the model instances and query and filter the information based on the
+client’s needs.
+
 Model relation in LoopBack 3 is one of its powerful features which help users
 define real-world mappings between their models, access sensible CRUD APIs for
 each of the models, and add querying and filtering capabilities for the relation
@@ -23,3 +38,7 @@ property on the source repository.
 Here are the currently supported relations:
 
 - [HasMany](HasMany-relation.md)
+
+The articles on each type of relation above will show you how to leverage the
+new relation engine to define and configure relations in your LoopBack
+application.