Address RR feedback

Author: mcmorisi

source/aggregation.txt

@@ -30,13 +30,13 @@ Overview
 In this guide, you can learn how to use the {+driver-short+} to perform
 **aggregation operations**.
 
-Aggregation operations process data in your MongoDB collections and
+You can use aggregation operations to process data in your MongoDB collections and
 return computed results. The MongoDB Aggregation framework, which is
-part of the Query API, is modeled on the concept of data processing
-pipelines. Documents enter a pipeline that contains one or more stages,
-and this pipeline transforms the documents into an aggregated result.
+part of the Query API, is modeled on the concept of a data processing
+pipeline. Documents enter a pipeline that contains one or more stages,
+and each stage transforms the documents to output a final aggregated result.
 
-An aggregation operation is similar to a car factory. A car factory has
+You can think of an aggregation operation as similar to a car factory. A car factory has
 an assembly line, which contains assembly stations with specialized
 tools to do specific jobs, like drills and welders. Raw parts enter the
 factory, and then the assembly line transforms and assembles them into a
@@ -46,8 +46,8 @@ The **aggregation pipeline** is the assembly line, **aggregation stages** are th
 assembly stations, and **operator expressions** are the
 specialized tools.
 
-Aggregation Versus Find Operations
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Compare Aggregation and Find Operations
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 You can use find operations to perform the following actions:
 
@@ -66,20 +66,19 @@ You can use aggregation operations to perform the following actions:
 Limitations
 ~~~~~~~~~~~
 
-Keep the following limitations in mind when using aggregation operations:
+The following limitations apply when using aggregation operations:
 
 - Returned documents must not violate the
   :manual:`BSON document size limit </reference/limits/#mongodb-limit-BSON-Document-Size>`
   of 16 megabytes.
 - Pipeline stages have a memory limit of 100 megabytes by default. You can exceed this
-  limit by using the ``allowDiskUse`` method of the
-  ``AggregateIterable`` type. 
+  limit by using the ``allowDiskUse()`` method from ``AggregateIterable`` class. 
 
 .. important:: $graphLookup exception
 
    The :manual:`$graphLookup
    </reference/operator/aggregation/graphLookup/>` stage has a strict
-   memory limit of 100 megabytes and ignores the ``allowDiskUse`` parameter.
+   memory limit of 100 megabytes and ignores the ``allowDiskUse`` option.
 
 Aggregation Example
 -------------------
@@ -100,18 +99,27 @@ The following {+language+} data class models the documents in this collection:
 Build and Execute an Aggregation Pipeline
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-To perform an aggregation, pass a list of aggregation stages to the
-``collection.aggregate()`` method.
+To perform an aggregation on the documents in a collection, pass a list of aggregation
+stages to the ``aggregate()`` method.
 
-The following code example produces a count of the number of bakeries in each borough
-of New York. To do so, it uses an aggregation pipeline with the following stages:
+This example outputs a count of the number of bakeries in each borough
+of New York City. The following code creates aggregation pipeline that contains the
+following stages:
 
 - A :manual:`$match </reference/operator/aggregation/match/>` stage to filter for documents
-  whose ``cuisine`` field contains the value ``"Bakery"``.
+  in which the value of the ``cuisine`` field is ``"Bakery"``.
 
 - A :manual:`$group </reference/operator/aggregation/group/>` stage to group the matching
-  documents by the ``borough`` field, accumulating a count of documents for each distinct
-  value.
+  documents by the ``borough`` field, producing a count of documents for each distinct
+  value of that field.
+
+.. TODO: uncomment when Aggregates Builder page is created
+
+.. .. note::
+
+..    The following example uses the builders pattern to implement the stages of an
+..    aggregation pipeline. To learn more about how to use the builders pattern, see
+..    :ref:`<aggregates-builders>`
 
 .. io-code-block::
 
@@ -131,18 +139,23 @@ of New York. To do so, it uses an aggregation pipeline with the following stages
       Document{{_id=Staten Island, count=20}}
       Document{{_id=Missing, count=2}}
 
+.. tip::
+
+   When specifying a group key for the ``$group`` aggregation stage, ensure that you
+   escape any ``$`` characters by using the ``\`` character. 
+
 Explain an Aggregation
 ~~~~~~~~~~~~~~~~~~~~~~
 
 To view information about how MongoDB executes your operation, you can
-instruct MongoDB to **explain** it. When MongoDB explains an operation, it returns
-**execution plans** and performance statistics. An execution
+include the ``$explain`` aggregation stage in your pipeline. When MongoDB explains an
+operation, it returns **execution plans** and performance statistics. An execution
 plan is a potential way MongoDB can complete an operation.
 When you instruct MongoDB to explain an operation, it returns both the
-plan MongoDB executed and any rejected execution plans.
+plan MongoDB selected for the operation and any rejected execution plans.
 
-The following code example runs the preceding aggregation example and prints the returned
-explanation:
+The following code example runs the same aggregation shown in the preceding section
+and adds the ``$explain`` stage to output the operation details:
 
 .. io-code-block::
 
@@ -156,43 +169,39 @@ explanation:
       :visible: false
 
       {
-        "explain": {
-          "aggregate": "restaurants",
-          "pipeline": [
-            {
-              "$match": {
-                "cuisine": "Bakery"
-              }
-            },
-            {
-              "$group": {
-                "_id": "$borough",
-                "count": {
-                  "$sum": 1
-                }
-              }
-            }
-          ],
-          "cursor": {}
-        },
-        ...
+        "explainVersion": "2", 
+        "queryPlanner": {
+            "namespace": "sample_restaurants.restaurants"
+            "indexFilterSet": false,
+            "parsedQuery": {
+              "cuisine": {"$eq": "Bakery"}
+            }, 
+            "queryHash": "865F14C3", 
+            "planCacheKey": "0697561B", 
+            "optimizedPipeline": true,
+            "maxIndexedOrSolutionsReached": false,
+            "maxIndexedAndSolutionsReached": false,
+            "maxScansToExplodeReached": false,
+            "winningPlan": { ... }
+            ...
+        }
       }
 
 Additional Information
 ----------------------
 
 To view a full list of expression operators, see :manual:`Aggregation
-Operators. </reference/operator/aggregation/>`
+Operators </reference/operator/aggregation/>` in the {+mdb-server+} manual.
 
 To learn about assembling an aggregation pipeline and view examples, see
-:manual:`Aggregation Pipeline. </core/aggregation-pipeline/>`
+:manual:`Aggregation Pipeline </core/aggregation-pipeline/>` in the {+mdb-server+} manual.
 
 To learn more about creating pipeline stages, see :manual:`Aggregation
-Stages. </reference/operator/aggregation-pipeline/>`
+Stages </reference/operator/aggregation-pipeline/>` in the {+mdb-server+} manual.
 
 To learn more about explaining MongoDB operations, see
 :manual:`Explain Output </reference/explain-results/>` and
-:manual:`Query Plans. </core/query-plans/>`
+:manual:`Query Plans </core/query-plans/>` in the {+mdb-server+} manual.
 
 .. Aggregation Tutorials
 .. ~~~~~~~~~~~~~~~~~~~~~

source/index.txt

@@ -82,7 +82,7 @@ section.
 Transform Your Data with Aggregation
 ------------------------------------
 
-Learn how to use the {+driver-short+} to perform aggregation operatoins in the
+Learn how to use the {+driver-short+} to perform aggregation operations in the
 :ref:`kotlin-sync-aggregation` section.
 
 Specialized Data Formats