just merging the changes and making the changes specified inline

draft/core/documents.txt → draft/core/document.txt

@@ -1,10 +1,14 @@
-=========
-Documents
-=========
+==============
+BSON Documents
+==============
 
 .. default-domain:: mongodb
 
-The document structure in MongoDB refer to the data structure of:
+MongoDB is a document-based database system, and as a result, all
+records, or data, in MongoDB are documents. Documents are the default
+representation of most user accessible data structures in the
+database. Documents provide structure for data in the following
+MongoDB contexts:
 
 - the :ref:`records <documents-records>` stored in :term:`collections
   <collection>`
@@ -22,13 +26,23 @@ The document structure in MongoDB refer to the data structure of:
   - :ref:`sort order <documents-sort-order>` for the :method:`sort()
     <cursor.sort()>` method.
 
+  - :ref:`index specification <documents-index>` for the
+    :method:`hint() <cursor.hint()>` method.
+
+- the various outputs from commands and operations, such as:
+
+  - the output of :dbcommand:`collStats` command
+
+  - the output of :doc:`db.serverStatus
+    </reference/server-status-index>` command
+
 Structure
 ---------
 
-The document structure in MongoDB are :term:`BSON` objects with support
-for the full range of :term:`BSON types`; however, conceptually,
-documents may be viewed as :term:`JSON` objects with the following
-structure:
+The document structure in MongoDB are :term:`BSON` objects with
+support for the full range of :term:`BSON types`; however, BSON
+documents are conceptually, similar to :term:`JSON` objects, and have
+the following structure:
 
 .. code-block:: javascript
 
@@ -45,13 +59,48 @@ documents may contain field and value pairs where the value can be
 another document, an array, an array of documents as well
 as the basic types such as ``Double``, ``String``, or ``Date``.
 
+Consider the following document that contains values of varying
+types:
+
+.. code-block:: javascript
+
+   {
+      _id: ObjectId("5099803df3f4948bd2f98391"),
+      name: { first: "Alan", last: "Turing" },
+      birth: new Date('Jun 23, 1912'),
+      death: new Date('Jun 07, 1954'),
+      contribs: [ "Turing machine", "Turing test", "Turingery" ],
+      views : NumberLong(1250000),
+      update : Timestamp(1352237167000, 1)
+   }
+
+The document contains the following fields:
+
+- field ``_id`` whose value is an *ObjectId*
+
+- field ``name`` whose value is another *Document* that contains the
+  fields ``first`` and ``last``
+
+- fields ``birth`` and ``death`` whose value is a *Date*
+
+- field ``contribs`` whose value is an *array of Strings*
+
+- field ``views`` whose value is a *NumberLong*
+
+- field ``update`` whose value is a *Timestamp*
+
+Types
+-----
+
 .. _documents-records:
 
-Document as records
--------------------
+Record Documents
+~~~~~~~~~~~~~~~~
 
-For documents that specify records to be stored in a collection, the
-following restrictions apply:
+Most documents in MongoDB are records in :term:`collections` which
+store data from users' applications. 
+
+These documents have the following limitations:
 
 - .. include:: /includes/fact-document-max-size.rst
 
@@ -92,18 +141,20 @@ The document contains the following fields:
 
 - field ``awards`` whose value is an *array of Documents*
 
-.. _documents-query-selectors:
-
-Document as query selectors
----------------------------
+.. not sure about the capitalization of Documents/Date/String here.
 
-Query selector documents may contain any or all of the following:
+.. _documents-query-selectors:
 
-- Simple field and value pair(s) to specify the equality
-  condition.
+Query Specification Documents
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-- :doc:`Query operator </reference/operators>` expressions to specify
-  other conditions.
+Query selector documents specify the conditions that determine which
+records to select for read, update, and delete operations. You can use
+field and value expressions to specify the equality condition and
+:doc:`query operator </reference/operators>` expressions to specify
+additional conditions. Refer to :doc:`read </applications/read>`,
+:doc:`update </applications/update>`, and :doc:`delete
+</applications/delete>` pages for more examples.
 
 Consider the following examples of query selector documents:
 
@@ -140,8 +191,8 @@ Consider the following examples of query selector documents:
 When passed as an argument to methods such as the :method:`find()
 <db.collection.find()>` method, the :method:`remove()
 <db.collection.remove()>` method, or the :method:`update()
-<db.collection.update()>` method, the query selector document
-determines which records are returned, removed, or updated:
+<db.collection.update()>` method, the query document selects documents
+for MongoDB to return, remove, or update, as in the following:
 
 .. code-block:: javascript
 
@@ -152,11 +203,15 @@ determines which records are returned, removed, or updated:
 
 .. _documents-update-actions:
 
-Document as update actions
---------------------------
+Update Specification Documents
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-The update actions documents contain :ref:`update operators
-<update-operators>` expressions.
+The update action documents specify the data modifications to perform
+during an :method:`update() <db.collection.update()>` operation to
+modify existing records in a collection. You can use :ref:`update
+operators <update-operators>` to specify the exact actions to perform
+on the document fields. See the :ref:`update operators
+<update-operators>` page for the available update operators and syntax.
 
 Consider the following example of an update actions document:
 
@@ -189,8 +244,13 @@ When passed as an argument to the :method:`update()
 
 .. _documents-index:
 
-Document as index
------------------
+Index Specifier Documents
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Indexes improve the efficiency of :doc:`read </applications/read>`
+operations. Index documents specify the fields to index on during the
+:method:`index creation <db.collection.ensureIndex()>` operation. See
+:doc:`indexes </core/indexes>` for an overview of indexes.
 
 The index documents contain field and value pairs where:
 
@@ -216,8 +276,14 @@ the index to create:
 
 .. _documents-sort-order:
 
-Document as sort order
-----------------------
+Sort Order Specification Documents
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The sort order documents specify the order of documents that a
+:method:`query() <db.collection.find()>` returns. The sort order
+document is passed as an argument to the :method:`sort()
+<cursor.sort()>` method. See the :method:`sort() <cursor.sort()>` page
+for more information on sorting.
 
 The sort order documents contain field and value pairs where:
 
@@ -226,7 +292,7 @@ The sort order documents contain field and value pairs where:
 - the ``value`` is either 1 for ascending or -1 for descending.
 
 The following document specifies the sort order using the fields from a
-subdocument ``name``: first sort by the ``last`` field ascending, then
+subdocument ``name`` first sort by the ``last`` field ascending, then
 by the ``first`` field also ascending:
 
 .. code-block:: javascript

source/includes/fact-document-max-size.rst

@@ -1,7 +1,7 @@
-Documents have a 16 megabytes size limit.
+The maximum BSON document size is 16 megabytes.
 
 The maximum document size helps ensure that a single document cannot
 use excessive amount of RAM or, during transmission, excessive amount
-of bandwidth. To store larger objects, MongoDB provides the
-GridFS API to handle documents larger than the maximum size. See your
-specific driver documentation for GridFS.
+of bandwidth. To store larger objects, MongoDB provides the GridFS API
+to handle documents larger than the maximum size. See your specific
+driver documentation for GridFS.

source/reference/limits.txt

@@ -19,7 +19,7 @@ BSON Documents
 .. _limit-bson-document-size:
 .. limit:: BSON Document Size
 
-   The maximum BSON document size is 16 megabytes.
+   .. include:: /includes/fact-document-max-size.rst
 
 .. _limit-nested-depth:
 .. limit:: Nested Depth for BSON Documents