DOCSP-8676 fix grammar and consistency (#51)

* DOCSP-8676 fix grammar and consistency across usage examples

Author: Chris Cho

.gitignore

@@ -7,3 +7,4 @@ build/
 giza.log
 .vscode*
 *.swp
+*.code-workspace

source/fundamentals/connection.txt

@@ -46,7 +46,7 @@ The last part of the connection string contains connection and authentication
 options as parameters. In the example above, we set two connection options:
 ``poolSize=20`` and ``useUnifiedTopology=true``.
 
-The code below shows how the sample connection URI could be used in a client to
+The code below shows how you can use the sample connection URI in a client to
 connect to MongoDB.
 
 .. literalinclude:: /code-snippets/connection/srv.js
@@ -101,8 +101,9 @@ URI to specify the behavior of the client.
    * - **validateOptions**
      - boolean
      - ``false``
-     - Specifies whether to error when an unknown or incorrect option is
-       provided. If ``false``, the driver produces warnings only.
+     - Specifies whether to error when the method parameters contain an
+       unknown or incorrect option. If ``false``, the driver produces warnings
+       only.
 
    * - **poolSize**
      - integer
@@ -131,7 +132,7 @@ URI to specify the behavior of the client.
    * - **keepAlive**
      - boolean
      - ``true``
-     - Specifies whether ``keepAlive`` is enabled on the TCP socket. For more
+     - Specifies whether to enable ``keepAlive`` on the TCP socket. For more
        information, see the documentation for `Node.js socket.setKeepAlive
        <https://nodejs.org/dist/latest-v10.x/docs/api/net.html#net_socket_setkeepalive_enable_initialdelay>`_.
 
@@ -200,7 +201,8 @@ URI to specify the behavior of the client.
      - boolean
      - ``true``
      - Specifies whether to promote BSON values to Node.js native types when
-       possible. When set to false, BSON values are presented as wrapper types.
+       possible. When set to false, it uses wrapper types to present
+       BSON values.
 
    * - **pkFactory**
      - object
@@ -223,7 +225,7 @@ URI to specify the behavior of the client.
    * - **logger**
      - object
      - ``null``
-     - Specifies a custom logger to be used by the client.
+     - Specifies a custom logger for the client to use.
 
    * - **tls**
      - boolean

source/fundamentals/crud.txt

@@ -73,9 +73,9 @@ Aggregate
 
 If you want to create custom processing pipelines for documents in a
 collection, you can use ``aggregate()``. This method accepts a
-pipeline of aggregation commands that are run in sequence. These
-commands let you filter, summarize, and augment documents in a
-collection into a result set for viewing.
+pipeline of aggregation commands to run in sequence. These commands let
+you filter, summarize, and augment documents in a collection into a result
+set for viewing.
 
 .. example::
 
@@ -92,11 +92,10 @@ collection into a result set for viewing.
 Watch / Subscribe
 ~~~~~~~~~~~~~~~~~
 
-If you want to monitor a collection for new, update, replace, and
-deleted documents that match a certain criteria, you can use
-``watch()``. This method takes a pipeline of aggregation commands that
-are run in sequence on new data whenever write operations are run on
-the collection.
+You can use the ``watch()`` method if you want to monitor a collection for
+new, update, replace, and deleted documents that match a certain criteria.
+You can pass this method a pipeline of aggregation commands that
+sequentially run on new data whenever write operations run on the collection.
 
 .. example::
 

source/fundamentals/logging.txt

@@ -56,9 +56,9 @@ level:
 Filter on a Specific Class
 --------------------------
 
-You can set the Logger to only produce log messages that are reported by
-specific classes. The following example demonstrates how to log messages from
-only the ``Db`` class.
+You can set the Logger to only produce log messages generated by specific
+classes. The following example demonstrates how to log messages from the
+``Db`` class only.
 
 .. code-block:: js
 
@@ -74,7 +74,7 @@ only the ``Db`` class.
      await db.command({ isMaster: true });
    }
 
-The driver classes that can be specified for filtering are as follows:
+You can specify the following driver classes for the logging filter:
 
 .. list-table::
    :header-rows: 1

source/fundamentals/monitoring.txt

@@ -14,11 +14,11 @@ Overview
 --------
 
 This guide shows you how to monitor topology events in a MongoDB instance,
-replica set, or sharded cluster. Topology events, also known as Server
-Discovery and Monitoring (SDAM) events, are created by the driver when there is
-a change in the state of the instance or cluster that you are connected to.
-For example, when a new connection is established or a new primary is elected,
-an event is created.
+replica set, or sharded cluster. The driver creates topology events, also
+known as Server Discovery and Monitoring (SDAM) events, when there is
+a change in the state of the instance or cluster that you connected to.
+For example, the driver creates an event when you establish a new connection
+or if the cluster elects a new primary.
 
 Read this guide if you need to record topology changes in your application or
 want to explore the information provided in these events.
@@ -38,8 +38,7 @@ deployment:
 Event Descriptions
 ------------------
 
-The following table lists all the SDAM events that are made available to your
-application by the driver:
+You can subscribe to any of the following SDAM events:
 
 .. list-table::
    :header-rows: 1
@@ -48,24 +47,24 @@ application by the driver:
      - Description
 
    * - ``serverOpening``
-     - Created when a connection to an instance is established.
+     - Created when a connection to an instance opens.
 
    * - ``serverClosed``
-     - Created when a connection to an instance is closed.
+     - Created when a connection to an instance closes.
 
    * - ``serverDescriptionChanged``
      - Created when an instance state changes (such as from secondary to
        primary).
 
    * - ``topologyOpening``
-     - Created before any instance connections are attempted.
+     - Created prior to attempting a connection to an instance.
 
    * - ``topologyClosed``
-     - Created after all instance connections in the topology are closed.
+     - Created after all instance connections in the topology close.
 
    * - ``topologyDescriptionChanged``
-     - Created when the topology changes, such as a new primary being
-       elected or a **mongos** proxy disconnecting.
+     - Created when the topology changes, such as an election of a new
+       primary or a **mongos** proxy disconnecting.
 
        *Not applicable to a single instance.*
 
@@ -75,8 +74,8 @@ application by the driver:
        *Not applicable to a single instance.*
 
    * - ``serverHeartbeatSucceeded``
-     - Created when a successful response to the ``isMaster`` command is
-       returned by a MongoDB instance.
+     - Created when the ``isMaster`` command returns successfully from a
+       MongoDB instance.
 
        *Not applicable to a single instance.*
 
@@ -156,8 +155,8 @@ one of the following possible values:
    * - ``Mongos``
      - Mongos proxy instance
    * - ``PossiblePrimary``
-     - At least one server recognizes this as the primary, but still needs to
-       be verified
+     - At least one server recognizes this as the primary, but is not yet
+       verified by all instances.
    * - ``RSPrimary``
      - Primary instance
    * - ``RSSecondary``

source/usage-examples/bulkWrite.txt

@@ -15,7 +15,7 @@ documentation for full details.
 ``bulkWrite()`` accepts the following parameters:
 
 - ``operations``: specifies the bulk operations to
-  perform. Each operation is passed to ``bulkWrite()`` as an object in
+  perform. Pass each operation to ``bulkWrite()`` as an object in
   an array.
 
 - ``options``: *optional* settings that affect the execution
@@ -57,7 +57,7 @@ same email address.
 
    Error during bulkWrite, BulkWriteError: E11000 duplicate key error collection: sample_mflix.users index: email_1 dup key: { : "rita_91@example.com" }
 
-Similarly, if you attempt to perform a bulk write against a  collection
+Similarly, if you attempt to perform a bulk write against a collection
 that uses :manual:`schema validation </core/schema-validation>`, you may
 encounter warnings or errors related to the formatting of inserted or
 modified documents.

source/usage-examples/command.txt

@@ -6,24 +6,22 @@ Run a Command
 
 You can run all raw database operations, not including
 :manual:`CRUD </crud/>` operations, using the :node-api:`command()
-<Admin.html#~command>` method. Typically ``command()`` is used for
-diagnostic and administrative tasks, such as fetching server stats or
-initializing a replica set.
+<Admin.html#~command>` method. Call the ``command()`` method with
+your command object on an instance of ``Admin`` for diagnostic and
+administrative tasks such as fetching server stats or initializing a replica
+set.
 
 .. note::
     Use :manual:`collection methods </reference/method/js-collection>`
-    instead of raw db commands whenever possible.
+    instead of raw database commands whenever possible.
 
-Create an :mdn:`Object
-<Web/JavaScript/Reference/Global_Objects/Object>`
-to specify additional options. Set the ``maxTimeMS`` field of this
-object to state  the number of milliseconds to wait before aborting the
+Create an object to specify options. Set the ``maxTimeMS`` field of this
+object to state the number of milliseconds to wait before terminating the
 query.
 
 The ``command()`` method returns a :mdn:`Promise
-<Web/JavaScript/Reference/Global_Objects/Promise>`
-that resolves to an object containing the return object of the operation
-that was run.
+<Web/JavaScript/Reference/Global_Objects/Promise>`. The Promise returns
+the results of the command operation when it completes.
 
 Example
 -------

source/usage-examples/count.txt

@@ -19,16 +19,14 @@ documents in a collection:
   collection metadata.
 
 ``estimatedDocumentCount()`` is faster than ``countDocuments()`` because
-the estimation is based on the collection's metadata rather than
-scanning the collection. In contrast,
-``countDocuments()`` takes longer to return, but provides an
-**accurate** count of the number of documents and supports specifying a
-filter. Choose the appropriate method for your workload.
+the estimation uses the collection's metadata rather than scanning the
+collection. In contrast, ``countDocuments()`` takes longer to return, but
+provides an **accurate** count of the number of documents and supports
+specifying a filter. Choose the appropriate method for your workload.
 
 To specify which documents you wish to count, ``countDocuments()``
 accepts a :doc:`query </fundamentals/crud/query-document>` parameter.
-``countDocuments()`` will only count the documents that match the
-specified query.
+``countDocuments()`` counts the documents that match the specified query.
 
 ``countDocuments()`` and ``estimatedDocumentCount()`` support optional
 settings that affect the method's execution. Refer to the reference

source/usage-examples/deleteMany.txt

@@ -4,37 +4,32 @@ Delete Multiple Documents
 
 .. default-domain:: mongodb
 
-You can delete several documents in a collection at once with
-``collection.deleteMany()``.
-The ``deleteMany()`` method uses a query document that you provide
-to match only the subset of the documents in the collection that match
-the query. If you don't provide a query document (or if you provide an
-empty document), MongoDB matches all documents in the collection. All
-matched documents are deleted. While you can use ``deleteMany()`` to
-delete all documents in a collection, consider using
-:node-api:`drop() <Collection.html#drop>`
-instead for better performance and clearer code.
-
-You can define additional query options using the ``options``
-object passed as the second parameter of the ``deleteMany()`` method.
-You can also pass a
-:node-api:`callback method
-<Collection.html#~deleteWriteOpCallback>`
-as an optional third parameter. For detailed reference documentation,
-see
-:node-api:`collection.deleteMany() <Collection.html#deleteMany>`.
-
-``deleteMany()`` behaves in two different ways depending on
-whether or not a callback method is provided:
-
-- if no callback method is provided, ``deleteMany()`` returns a
+You can delete several documents in a collection at once using the
+:node-api:`collection.deleteMany() <Collection.html#deleteMany>` method.
+Pass a query document to the ``deleteMany()`` method to specify a subset
+of documents in the collection to delete. If you do not provide a query
+document (or if you provide an empty document), MongoDB matches all documents
+in the collection and deletes them. While you can use ``deleteMany()``
+to delete all documents in a collection, consider using
+:node-api:`drop() <Collection.html#drop>` instead for better performance
+and clearer code.
+
+You can specify additional options in the ``options`` object passed in
+the second parameter of the ``deleteMany()`` method. You can also pass a
+:node-api:`callback method <Collection.html#~deleteWriteOpCallback>`
+as an optional third parameter. For more detailed information, see
+:node-api:`the deleteMany() API documentation <Collection.html#deleteMany>`.
+
+``deleteMany()`` behaves in two different ways depending on whether you
+provide a callback method:
+
+- if you do not specify a callback method, ``deleteMany()`` returns a
   :mdn:`Promise <Web/JavaScript/Reference/Global_Objects/Promise>`
-  that resolves to an
-  :mdn:`Object <Web/JavaScript/Reference/Global_Objects/Object>`
+  that resolves to an object
 
-- if a callback method is provided, ``deleteMany()`` returns
-  nothing, and instead passes the result object or error object to the
-  provided callback method
+- if you specify a callback method, ``deleteMany()`` returns
+  nothing, and instead passes the result or error object to the
+  callback method
 
 The
 :node-api:`result object <Collection.html#~deleteWriteOpResult>`
@@ -50,7 +45,7 @@ Example
 
 The following snippet deletes multiple documents from the ``movies``
 collection. It uses a **query document** that configures the query to
-match and delete only movies with the title "Santa Claus".
+match and delete movies with the title "Santa Claus".
 
 .. literalinclude:: /code-snippets/usage-examples/deleteMany.js
   :language: javascript

source/usage-examples/deleteOne.txt

@@ -7,36 +7,35 @@ Delete a Document
 You can delete a single document in a collection with
 ``collection.deleteOne()``.
 The ``deleteOne()`` method uses a query document that you provide
-to match only the subset of the documents in the collection that match
-the query. If you don't provide a query document (or if you provide an
-empty document), MongoDB matches all documents in the collection.
-However, only the first matched document is deleted.
+to match the subset of the documents in the collection that match
+the query. If you do not provide a query document (or if you provide an
+empty document), MongoDB matches all documents in the collection and
+deletes the first match.
 
-You can define additional query options using the
+You can specify additional query options using the
 ``options`` object passed as the second parameter of the
 ``deleteOne`` method. You can also pass a
 :node-api:`callback method <Collection.html#~deleteWriteOpCallback>`
 as an optional third parameter. For detailed reference documentation,
-see :node-api:`collection.deleteOne() <Collection.html#deleteOne>`.
+see :node-api:`deleteOne() <Collection.html#deleteOne>`.
 
 ``deleteOne()`` behaves in two different ways depending on
-whether or not a callback method is provided:
+whether you provide a callback method:
 
-- if no callback method is provided, ``deleteOne()`` returns a
+- if you do not specify a callback method, ``deleteOne()`` returns a
   :mdn:`Promise <Web/JavaScript/Reference/Global_Objects/Promise>`
-  that resolves to an
-  :mdn:`Object <Web/JavaScript/Reference/Global_Objects/Object>`
+  that resolves to an object
 
-- if a callback method is provided, ``deleteOne()`` returns
+- if you specify a callback method, ``deleteOne()`` returns
   nothing, and instead passes the result object or error object to the
-  provided callback method
+  callback method
 
 The :node-api:`result object
 <Collection.html#~deleteWriteOpResult>`
 contains several keys in the event of a successful execution. You can
 use the ``deletedCount`` key to check the number of documents deleted by
-the operation. Since ``deleteOne()`` can only delete  a single document,
-``deletedCount`` can only have a value of ``0`` or ``1``.
+the operation. Since ``deleteOne()`` can only delete a single document,
+``deletedCount`` can have a value of either ``0`` or ``1``.
 
 The error object contains ``errmsg``, a human-readable explanation of
 what caused the operation to fail.