Updates to the DBRef page

source/reference/database-references.txt

@@ -19,28 +19,30 @@ MongoDB applications use one of two methods for relating documents:
 
 #. :ref:`Manual references <document-references>` where you save the
    ``_id`` field of one document in another document as a reference.
-   Then your application can run a second query to return the embedded
+   Then your application can run a second query to return the related
    data. These references are simple and sufficient for most use
    cases.
 
 #. :ref:`DBRefs <dbref>` are references from one document to another
-   using the value of the first document's ``_id`` field collection,
-   and optional database name. To resolve DBRefs, your application
+   using the value of the first document's ``_id`` field, collection name,
+   and, optionally, its database name. By including these names, DBRefs
+   allow documents located in multiple collections to be more easily linked
+   with documents from a single collection.
+
+   To resolve DBRefs, your application
    must perform additional queries to return the referenced
    documents. Many :doc:`drivers </applications/drivers>` have helper
    methods that form the query for the DBRef automatically. The
    drivers [#official-driver]_ do not *automatically* resolve DBRefs
    into documents.
 
-   Use a DBRef when you need to embed documents from multiple
-   collections in documents from one collection. DBRefs also provide a
-   common format and type to represent these relationships among
-   documents. The DBRef format provides common semantics for representing
+   DBRefs provide a common format and type to represent relationships among
+   documents. The DBRef format also provides common semantics for representing
    links between documents if your database must interact with
    multiple frameworks and tools.
 
-Unless you have a compelling reason for using a DBRef, use manual
-references.
+Unless you have a compelling reason to use DBRefs, use manual
+references instead.
 
 .. [#official-driver] Some community supported drivers may have
    alternate behavior and may resolve a DBRef into a document
@@ -54,7 +56,7 @@ Manual References
 Background
 ~~~~~~~~~~
 
-Manual references refers to the practice of including one
+Using manual references is the practice of including one
 :term:`document's <document>` ``_id`` field in another document. The
 application can then issue a second query to resolve the referenced
 fields as needed.
@@ -95,7 +97,7 @@ references are simple to create and your application can resolve
 references as needed.
 
 The only limitation of manual linking is that these references do not
-convey the database and collection name. If you have documents in a
+convey the database and collection names. If you have documents in a
 single collection that relate to documents in more than one
 collection, you may need to consider using :ref:`DBRefs <dbref>`.
 
@@ -109,7 +111,7 @@ Background
 
 DBRefs are a convention for representing a :term:`document`, rather
 than a specific reference type. They include the name of the
-collection, and in some cases the database, in addition to the
+collection, and in some cases the database name, in addition to the
 value from the ``_id`` field.
 
 Format
@@ -138,7 +140,7 @@ DBRefs have the following fields:
 
 .. example::
 
-   DBRef document would resemble the following:
+   DBRef documents resemble the following document:
 
    .. code-block:: javascript
 
@@ -159,7 +161,7 @@ DBRefs have the following fields:
                      }
       }
 
-   The DBRef in this example, points to a document in the ``creators``
+   The DBRef in this example points to a document in the ``creators``
    collection of the ``users`` database that has
    ``ObjectId("5126bc054aed4daf9e2ab772")`` in its ``_id`` field.
 
@@ -195,7 +197,7 @@ Support
    <http://search.cpan.org/dist/MongoDBx-AutoDeref/>`_ CPAN module.
 
 **PHP**
-   The PHP driver does support DBRefs, including the optional ``$db`` reference, through
+   The PHP driver supports DBRefs, including the optional ``$db`` reference, through
    `The MongoDBRef class <http://www.php.net/manual/en/class.mongodbref.php/>`_.
 
 **Python**
@@ -205,12 +207,11 @@ Support
 
 **Ruby**
    The Ruby Driver supports DBRefs using the :api:`DBRef class </ruby/current/BSON/DBRef.html>`
-   and the :api:`deference method </ruby/current/Mongo/DB.html#dereference>`.
+   and the :api:`deference method </ruby/current/Mongo/DB.html#dereference-instance_method>`.
 
 Use
 ~~~
-
 In most cases you should use the :ref:`manual reference
 <document-references>` method for connecting two or more related
 documents. However, if you need to reference documents from multiple
-collections, consider a DBRef.
+collections, consider using DBRefs.