DOCS-617 field order, write concern, and minor edits

Author: kay-kim

draft/applications/create.txt

@@ -31,10 +31,12 @@ the create operation:
 
 MongoDB v2.2 has a 16 megabytes limit on document size.
 
-.. include:: /includes/note-write-concerns.rst
-
 .. include:: /includes/warning-document-field-name-restrictions.rst
 
+.. note::
+
+   .. include:: /includes/fact-write-concerns.rst
+
 .. _crud-create-insert:
 
 Insert

draft/applications/delete.txt

@@ -8,7 +8,9 @@ Delete operation removes documents from a :term:`collection`. MongoDB
 provides the :ref:`remove() <crud-delete-remove>` method to perform
 delete operations.
 
-.. include:: /includes/note-write-concerns.rst
+.. note::
+
+   .. include:: /includes/fact-write-concerns.rst
 
 .. _crud-delete-remove:
 

draft/applications/update.txt

@@ -12,7 +12,11 @@ methods to perform update operations:
 
 - :ref:`save <crud-update-save>`
 
-.. include:: /includes/note-write-concerns.rst
+.. note::
+
+   - .. include:: /includes/fact-update-field-order.rst
+
+   - .. include:: /includes/fact-write-concerns.rst
 
 .. _crud-update-update:
 

draft/core/read-operations.txt

@@ -23,9 +23,9 @@ iterates over the result set of matching :term:`documents` in a collection.
 
 .. index:: read operations; query
 .. index:: query; read operations
-.. _read-operations-query-operations:
+.. _read-operations-query-operators:
 
-Read Operations
+Read Operators
 ---------------
 
 In the :program:`mongo` shell the :method:`find()
@@ -46,21 +46,19 @@ syntax:
   in the :program:`mongo` shell to list the current collections in the
   database.
 
-- Queries in MongoDB have a JSON-like syntax, and take the form of a
-  :term:`document` using a collection of :doc:`/reference/operators`
-  query operators to describe query parameters.
+- The ``<query>`` argument specifies the selection criteria in the form
+  of JSON-like :doc:`core/documents` that use a set of
+  :doc:`/reference/operators` to specify the query conditions.
 
-  The ``<query>`` argument of the :method:`find()
-  <db.collection.find()>` method holds this query document. A query,
-  without a query document will return all documents in the
-  collection.
+  The :method:`find() <db.collection.find()>` method without a query
+  argument will return all documents in the collection.
 
-- The ``<projection>`` argument describes describes the result or
-  return set in the form of a document. Projections specify or limit
+- The ``<projection>`` argument describes the result set
+  in the form of a document. Projections specify or limit
   the fields to return.
 
   Without a projection the operation will return all
-  fields of all documents, specify a projection if your documents are
+  fields of all documents. Specify a projection if your documents are
   larger, or when your application only needs a subset of available
   fields.
 
@@ -158,7 +156,7 @@ query. Consider the following example query operations using the
 
      db.inventory.find( { tags: "fruit" } )
 
-MongoDB provides a full complement of query selection operators such
+MongoDB provides a full range of query selection operators such
 as the :operator:`$lt` operator and the :operator:`$or`
 operator. Refer to the :doc:`/reference/operators` document for the
 complete list of query selection operators.
@@ -168,13 +166,13 @@ complete list of query selection operators.
 Projection Argument
 ~~~~~~~~~~~~~~~~~~~
 
-The :term:`projection` specification, limits the fields to return for
-all matching. By narrowing the fields to return, projections can
-minimize network transit costs and the costs of deserializing document
-in the applications. In the ``<projection>`` argument, you can either
-specify the fields to include (``field:1``) or specify the fields to
-exclude (``field:0``). The ``_id`` field is implicitly included,
-unless explicitly excluded.
+The :term:`projection` specification limits the fields to return for
+all matching documents. By narrowing the fields to return, projections
+can minimize network transit costs and the costs of deserializing
+document in the applications. In the ``<projection>`` argument, you can
+either specify the fields to include (``field:1``) or specify the
+fields to exclude (``field:0``). The ``_id`` field is implicitly
+included, unless explicitly excluded.
 
 .. note::
 
@@ -217,9 +215,9 @@ Consider the following projection specifications, in the
 
      db.inventory.find( { type: 'food' }, { type:0 } )
 
-MongoDB also provides the following projection operators, that allow
-richer projection specifications for fields that hold arrays. Refer to
-the operator documentation for the :projection:`$elemMatch` and
+MongoDB also provides the projection operators that allow richer
+projection specifications for fields that hold arrays. Refer to the
+operator documentation for the :projection:`$elemMatch` and
 :projection:`$slice` operators.
 
 .. _read-operations-indexing:
@@ -228,10 +226,10 @@ Indexes
 -------
 
 Indexes improve the efficiency of read operations by reducing the work
-associated with fulfilling queries, by building a special structure
-and maintain that structure when inserting or modifying
-documents. These indexes support specific queries, sort operations,
-and allow for more efficient storage utilization.
+associated with fulfilling queries, by building a special structure and
+maintaining that structure during insert and update operations. These
+indexes support specific queries and sort operations, and allow for
+more efficient storage utilization.
 
 Create indexes using the :method:`db.collection.ensureIndex{)` method
 in the :program:`mongo` shell, as in the following prototype
@@ -286,8 +284,8 @@ To improve the performance of the query, create an index on the
 
    db.inventory.ensureIndex( { type: 1 } )
 
-Compare the performance of the previous read operation, but now
-executed with the newly created index:
+Compare the performance of the previous read operation now executed
+with the newly created index:
 
 .. code-block:: javascript
 
@@ -434,7 +432,7 @@ following methods and commands:
 
 - :method:`group()`
 
-- :dbcommand:`mapReduce() <mapreduce>` (See also :wiki:`MapReduce`.)
+- :dbcommand:`mapReduce() <mapreduce>`
 
 .. index:: read operation; architecture
 .. _read-operations-architecture:
@@ -444,12 +442,6 @@ Architecture
 
 .. index:: read operation; connection pooling
 .. index:: connection pooling; read operations
-.. _read-operations-connection-pooling:
-
-Connection Pooling
-~~~~~~~~~~~~~~~~~~
-
-.. TODO
 
 Sharded Clusters
 ~~~~~~~~~~~~~~~~

draft/core/write-operations.txt

@@ -4,9 +4,8 @@ Write Operations
 
 .. default-domain:: mongodb
 
-Write operations create, update, and delete data in MongoDB databases.
-MongoDB databases store data as :term:`documents <document>` in
-:term:`collections <collection>`.
+Write operations create, update, and delete data. MongoDB stores data
+as :term:`documents <document>` in :term:`collections <collection>`.
 
 This section of the manual describes how MongoDB performs write
 operations and how different factors affect the efficiency of those

source/includes/fact-update-field-order.rst

@@ -0,0 +1,5 @@
+When performing update operations that increase the document size
+beyond the allocated space for that document, the update operation
+relocates the document on disk and orders the document fields
+alphanumerically.
+

source/includes/fact-write-concerns.rst

@@ -0,0 +1,9 @@
+By default, all write operations will issue a :dbcommand:`getLastError`
+command to confirm the result of the write operation:
+   
+.. code-block:: javascript
+
+   { getLastError: 1 }
+
+Refer to the documentation on :ref:`write concern <write-concern>` and
+:doc:`/applications/write-operations` for more information.