DOCSP-15177 definition of builders (#90)

* added a more in depth definition of builders

Author: kyuan-mongodb

source/fundamentals/builders.txt

@@ -19,35 +19,66 @@ Builders
    :depth: 2
    :class: singlecol
 
-This section includes guides on how to use each of the available builders, and demonstrates the utility the Java driver
-builder classes provide.
+This section includes guides on how to use each of the available
+builders, and demonstrates the utility the Java driver builder classes
+provide. 
 
 Overview
 --------
 
-The Java driver provides classes to make it easier to use CRUD operations and the Aggregation API. The static utility methods
-allow you to build a query more succinctly.
+The Java driver provides classes to simplify the process for developers
+to use CRUD operations and the Aggregation API. The static utility methods allow you
+to build a query more efficiently. 
 
+Why Use Builders?
+-----------------
 
-Imagine we want to send a marketing email to all users in our users collection that identify as "female" gender and are older than "29".
-We only need their email address, so we'll ensure our query doesn't return data we pay bandwidth
-costs for but don't need.
+Using the builders class, you leverage the power of:
 
-Using JSON and the MongoDB shell, the query would look something like:
+- The Java compiler and the IDE to find errors during development
+- The IDE for discovery and code completion
+
+The Java compiler and the IDE catch errors such as misspelled
+operators early on. When using the MongoDB shell or plain Java, you
+write operators as strings and get no visual indication of a problem,
+pushing these errors to runtime instead of compile time
+
+With the builder classes, you write operators as methods. The IDE
+instantly underlines and gives you a red bar on the right indicating
+something is wrong. While developing, the IDE also shows you with the
+methods you can use. It automatically completes your code with
+placeholder parameters once you select which method you want to use. 
+
+Scenario
+--------
+
+Imagine we want to send a marketing email to all users in our ``users``
+collection with the following criteria:
+
+- Users that identify as "female" gender 
+- Users that are older than "29"
+
+We only want their email address, so we'll ensure our query doesn't
+return data we pay bandwidth costs for but don't need.
+
+Using the MongoDB Shell
+~~~~~~~~~~~~~~~~~~~~~~~
 
 .. code-block:: js
 
    collection.find({ "gender": "female", "age" : { "$gt": 29 }}, { "_id": 0, "email": 1 })
 
-Without builders, we construct the query in Java as:
+Without Using Builders
+~~~~~~~~~~~~~~~~~~~~~~
 
 .. code-block:: java
 
-   Bson filter = new Document().append("gender", "female").append("age", new Document().append("$gt", 28));
+   Bson filter = new Document().append("gender", "female").append("age", new Document().append("$gt", 29));
    Bson projection = new Document().append("_id", 0).append("email", 1);
    collection.find(filter).projection(projection);
 
-With builders, the query becomes:
+Using Builders
+~~~~~~~~~~~~~~
 
 .. code-block:: java
 

source/fundamentals/builders/filters.txt

@@ -14,14 +14,13 @@ Filters Builders
 
 Overview 
 --------
+
 In this guide, we show you how to use **builders** to specify
 **filters** for your queries.
 
-Builders are classes provided by the MongoDB Java driver that allow you
-to use the builder pattern to interact with your MongoDB instance. The
-builders provided by the MongoDB Java driver can improve the readability
-of your code.  See the :doc:`Builders </fundamentals/builders/>` page
-for a list of Builders available in the Java driver. 
+Builders are classes provided by the MongoDB Java driver that help you
+construct :ref:`Bson <bson>` objects. To learn more, see our :doc:`guide
+on builders </fundamentals/builders/>`. 
 
 Filters are the operations MongoDB uses to limit your results to what
 you want to see. 

source/fundamentals/builders/indexes.txt

@@ -15,9 +15,9 @@ Indexes Builders
 Overview 
 --------
 
-This guide shows you how to specify **indexes** using the Java Driver
-:doc:`builders </fundamentals/builders/>`. Index builders provide
-helper methods for the following types of indexes:
+In this guide, we show you how to specify **indexes** using the Java
+Driver :doc:`builders </fundamentals/builders/>`. Index builders provide
+helper methods for the following types of indexes: 
 
 - :ref:`Ascending Indexes <ascending-indexes>`
 - :ref:`Descending Indexes <descending-indexes>`

source/fundamentals/builders/projections.txt

@@ -15,6 +15,9 @@ Projections Builders
 Overview
 --------
 
+In this guide, we show you how to specify **projections** using the Java
+Driver :doc:`builders </fundamentals/builders/>`.
+
 MongoDB supports **field projection**, specifying which fields to include and exclude when returning results from a
 query. Projection in MongoDB follows some basic rules:
 

source/fundamentals/builders/sort.txt

@@ -25,9 +25,9 @@ examples of sort criteria are:
 * Earliest time of day to latest time of day
 * Alphabetical order by first name 
 
-Builders are classes provided by the MongoDB Java driver that help you construct 
-:java-docs:`Bson <apidocs/bson/org/bson/conversions/Bson.html>` objects. 
-To learn more, see our :doc:`guide on builders </fundamentals/builders/>`.
+Builders are classes provided by the MongoDB Java driver that help you
+construct :ref:`Bson <bson>` objects. To learn more, see our :doc:`guide
+on builders </fundamentals/builders/>`. 
 
 You should read this guide if you would like to use builders to specify sort
 criteria for your queries.

source/fundamentals/builders/updates.txt

@@ -16,8 +16,9 @@ Overview
 --------
 
 This guide shows you how to specify **updates** using the Java Driver
-:doc:`builders </fundamentals/builders/>`. Update builders provide
-helper methods for the following types of updates:
+:doc:`builders </fundamentals/builders/>`. 
+
+Update builders provide helper methods for the following types of updates:
 
 - :ref:`Field Updates <field_updates>`
 - :ref:`Array Updates <array_updates>`