Address RR feedback

Author: mcmorisi

source/builders.txt

@@ -1,8 +1,8 @@
 .. _kotlin-sync-builders:
 
-================
-Use Builders API
-================
+===============================
+Implement Builders Code Pattern
+===============================
 
 .. contents:: On this page
    :local:
@@ -22,29 +22,31 @@ Use Builders API
 Overview
 --------
 
-This page describes how to use the builders API and demonstrates the utility provided by
-builder classes.
+This page describes how to implement the builders pattern in your code and describes
+benefits of using builder classes.
 
-The {+driver-short+} provides type-safe classes and methods that enable developers to
-efficiently build queries and aggregations.
+The {+driver-short+} provides type-safe builders classes and methods that enable developers to
+efficiently build queries and aggregations. To learn more about the builders pattern,
+see `Type-safe builders <https://kotlinlang.org/docs/type-safe-builders.html>`__ in the
+{+language+} documentation.
 
-Why Use Builders?
------------------
+Why Use the Builders Code Pattern?
+----------------------------------
 
-When using the MongoDB shell or plain Kotlin to construct BSON query documents, you are not
+If you use only plain {+language+} to construct BSON query documents, you are not
 able to identify errors in your code until runtime.
 
-With builder classes, you can write operators as methods and any syntax errors will be
-caught at compile time.
+When you use builder classes, you can write operators as methods and any syntax errors
+will be caught at compile time.
 
 Example
 -------
 
-This section describes three methods of fetching the ``email`` field values of documents
+This section provides three equivalent ways to fetch the ``email`` field values of documents
 in the ``users`` collection that meet the following criteria:
 
-- Users that identify as ``female``
-- Users that are older than ``29``
+- ``gender`` value is ``"female"``
+- ``age`` value is greateer than ``29``
 
 The following data class models the documents in the ``users`` collection:
 
@@ -64,19 +66,20 @@ The following data class models the results returned by our query:
    :copyable:
    :dedent:
 
-Using the MongoDB Shell
-~~~~~~~~~~~~~~~~~~~~~~~
+MongoDB Query API
+~~~~~~~~~~~~~~~~~
 
-The following sample executes the previously defined query using the MongoDB shell:
+The following sample performs the query by using the MongoDB Query API:
 
 .. code-block:: js
 
    collection.find({ "gender": "female", "age" : { "$gt": 29 }}, { "_id": 0, "email": 1 })
 
-Without Using Builders
-~~~~~~~~~~~~~~~~~~~~~~
+Document Class Filter
+~~~~~~~~~~~~~~~~~~~~~
 
-The following example executes the previously defined query using plain {+language+}:
+The following example performs the query by using the ``Document`` class to construct the
+query filter:
 
 .. literalinclude:: /includes/builders/builders.kt
    :start-after: start-find
@@ -85,10 +88,10 @@ The following example executes the previously defined query using plain {+langua
    :copyable:
    :dedent:
 
-Using Builders
-~~~~~~~~~~~~~~
+Builders Pattern
+~~~~~~~~~~~~~~~~
 
-The following example executes the previously defined query using the builders API:
+The following example performs the query by using the builders pattern:
 
 .. literalinclude:: /includes/builders/builders.kt
    :start-after: start-find-builders
@@ -102,6 +105,9 @@ The following example executes the previously defined query using the builders A
 .. Available Builders
 .. ------------------
 
+.. The following pages describe how to implement the different classes of builders
+.. available in the {+driver-short+}.
+
 .. - :ref:`Aggregates <aggregates-builders>` for building aggregation pipelines.
 .. - :ref:`Filters <filters-builders>` for building query filters.
 .. - :ref:`Indexes <indexes-builders>` for creating index keys.

source/includes/builders/builders.kt

@@ -9,16 +9,15 @@ import org.bson.types.ObjectId
 
 // start-user-class
 data class User(
-    @BsonId
-    val id: ObjectId,
+    @BsonId val id: ObjectId,
     val gender: String,
     val age: Int,
     val email: String
 )
 // end-user-class
 
 // start-result-class
-data class Result(
+data class Email(
     val email: String
 )
 // end-result-class
@@ -38,7 +37,7 @@ fun main() {
     // start-find
     val filter = Document("gender", "female").append("age", Document("\$gt", 29))
     val projection = Document("_id", 0).append("email", 1)
-    val results = collection.find<Result>(filter).projection(projection)
+    val results = collection.find<Email>(filter).projection(projection)
     // end-find
 
     // start-find-builders
@@ -52,7 +51,7 @@ fun main() {
         Projections.include("email")
     )
 
-    val results = collection.find<Result>(filter).projection(projection)
+    val results = collection.find<Email>(filter).projection(projection)
     // end-find-builders
 }