DOCS-617 merge and edit the bson doc

Author: kay-kim

draft/core/documents.txt renamed to draft/core/document.txt

@@ -4,10 +4,10 @@ BSON Documents
 
 .. default-domain:: mongodb
 
-MongoDB is a document-based database system, and as a result all
-records, or data in MongoDB are documents. Documents are the default
+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. Document's provide structure for data in the following
+database. Documents provide structure for data in the following
 MongoDB contexts:
 
 - the :ref:`records <documents-records>` stored in :term:`collections
@@ -26,10 +26,15 @@ MongoDB contexts:
   - :ref:`sort order <documents-sort-order>` for the :method:`sort()
     <cursor.sort()>` method.
 
-  - index specification for the :method:`hint() <cursor.hint()>`
-    method.
+  - :ref:`index specification <documents-index>` for the
+    :method:`hint() <cursor.hint()>` method.
 
-.. status output, link to examples of server stats/coll stats/etc. (?)
+- 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
 ---------
@@ -54,13 +59,35 @@ 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``.
 
-.. give more examples of:
+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*
 
-   - special bson types NumberLong(), Timestamp, etc.
+- field ``contribs`` whose value is an *array of Strings*
 
-   - nested document.
+- field ``views`` whose value is a *NumberLong*
 
-   - with arrays
+- field ``update`` whose value is a *Timestamp*
 
 Types
 -----
@@ -71,17 +98,14 @@ Record Documents
 ~~~~~~~~~~~~~~~~
 
 Most documents in MongoDB are records in :term:`collections` which
-store data from users' applications. These documents have the
-following limitations:
+store data from users' applications. 
+   
+These documents have the following limitations:
 
 - .. include:: /includes/fact-document-max-size.rst
 
 - .. include:: /includes/fact-document-field-name-restrictions.rst
 
-.. these should be links to the limit page or include those links. We
-   should make these things centrally referenced to limit the number
-   of places these data points exist *if* any of them ever change.
-
 .. include:: /includes/note-insert-id-field.rst
 
 The following document specifies a record in a collection:
@@ -124,19 +148,13 @@ The document contains the following fields:
 Query Specification Documents
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-.. this section should have a better lead in. I think we should be
-   able to avoid the bulleted list here, which affects flow...
-
-Query selector documents may contain any or all of the following:
-
-- Simple field and value pair(s) to specify the equality
-  condition.
-
-.. we should attempt to avoid issuing qualitative judgements about
-   complexity or simplicity.
-
-- :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:
 
@@ -188,10 +206,12 @@ for MongoDB to return, remove, or update, as in the following:
 Update Specification Documents
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-.. when are they used, links to cross reference material to provide context
-
-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:
 
@@ -227,8 +247,10 @@ When passed as an argument to the :method:`update()
 Index Specifier Documents
 ~~~~~~~~~~~~~~~~~~~~~~~~~
 
-.. what are index documents? when are they used? cross reference links
-   would provide a lot of the required documentation.
+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:
 
@@ -257,7 +279,11 @@ the index to create:
 Sort Order Specification Documents
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-.. where? context?
+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:
 
@@ -266,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