From f748127d88cc26dd7aa537b7f9ef7c5f610590c8 Mon Sep 17 00:00:00 2001
From: Andrew Aldridge <i80and@foxquill.com>
Date: Mon, 29 Sep 2014 12:52:50 -0400
Subject: [PATCH] DOCS-4062: Natural order clarification

---
 source/reference/glossary.txt              | 18 ++++++------------
 source/reference/method/cursor.sort.txt    | 15 +++++++++------
 source/reference/operator/meta/natural.txt |  7 ++++---
 3 files changed, 19 insertions(+), 21 deletions(-)

diff --git a/source/reference/glossary.txt b/source/reference/glossary.txt
index 4743de74704..c63f4757df2 100644
--- a/source/reference/glossary.txt
+++ b/source/reference/glossary.txt
@@ -498,18 +498,12 @@ Glossary
       belong to a namespace. See :ref:`faq-dev-namespace`.
 
    natural order
-      The order that a database stores documents on disk. Typically,
-      the order of documents on disks reflects insertion order, except
-      when a document moves internally because an update operation
-      increases its size. In :term:`capped collections <capped
-      collection>`, insertion order and natural order are identical
-      because documents do not move internally. MongoDB returns
-      documents in forward natural order for a
-      :method:`~db.collection.find()` query with no parameters.
-      MongoDB returns documents in reverse natural order for a
-      :method:`~db.collection.find()` query :method:`sorted
-      <cursor.sort()>` with a parameter of ``$natural:-1``. See
-      :operator:`$natural`.
+      The order in which the database refers to documents on disk. This is the
+      default sort order. See :operator:`$natural` and
+      :ref:`return-natural-order`.
+
+   storage order
+      See :term:`natural order`.
 
    ObjectId
       A special 12-byte :term:`BSON` type that guarantees uniqueness
diff --git a/source/reference/method/cursor.sort.txt b/source/reference/method/cursor.sort.txt
index b047e21d1b8..595aa55d125 100644
--- a/source/reference/method/cursor.sort.txt
+++ b/source/reference/method/cursor.sort.txt
@@ -189,14 +189,17 @@ The query returns the following documents, ordered first by the
    { "_id" : 3, "item" : { "category" : "cookies", "type" : "chocolate chip" }, "amount" : 15 }
 
 .. _return-storage-order:
+.. _return-natural-order:
 
-Return in Storage Order
+Return in Natural Order
 -----------------------
 
 The :operator:`$natural` parameter returns items according to their
-storage order within the collection level extents.
+:term:`natural order` within the database. This ordering is an internal
+implementation feature, and you should not rely on any particular structure
+within it.
 
-Typically, the storage order reflects insertion order, *except* when
+Typically, the natural order reflects insertion order, *except* when
 documents relocate because of :ref:`document growth due to updates
 <data-model-document-growth>` or remove operations free up space which
 are then taken up by newly inserted documents.
@@ -212,7 +215,7 @@ Consider the sequence of insert operations to the ``trees`` collection:
    db.trees.insert( { _id: 3, common_name: "maple", genus: "aceraceae" } )
    db.trees.insert( { _id: 4, common_name: "birch", genus: "betula" } )
 
-The following query returns the documents in the storage order:
+The following query returns the documents in the natural order:
 
 .. code-block:: javascript
 
@@ -236,13 +239,13 @@ Update a document such that the document outgrows its current allotted space:
       { $set: { famous_oaks: [ "Emancipation Oak", "Goethe Oak" ] } }
    )
 
-Rerun the query to returns the documents in the storage order:
+Rerun the query to returns the documents in natural order:
 
 .. code-block:: javascript
 
    db.trees.find().sort( { $natural: 1 } )
 
-The documents return in the following storage order:
+The documents return in the following natural order:
 
 .. code-block:: javascript
 
diff --git a/source/reference/operator/meta/natural.txt b/source/reference/operator/meta/natural.txt
index 1f37721ca62..23d5a03afb5 100644
--- a/source/reference/operator/meta/natural.txt
+++ b/source/reference/operator/meta/natural.txt
@@ -10,8 +10,9 @@ Definition
 .. operator:: $natural
 
   Use the :operator:`$natural` operator to use :term:`natural order` for
-  the results of a sort operation. Natural order refers to the
-  :ref:`storage order <return-storage-order>` of documents in the file on disk.
+  the results of a sort operation. Natural order refers to the logical
+  :ref:`ordering <return-natural-order>` of documents internally within the
+  database.
 
   The :operator:`$natural` operator uses the following syntax to return
   documents in the order they exist on disk:
@@ -24,7 +25,7 @@ Behavior
 --------
 
 On a sharded collection the :operator:`$natural` operator returns a
-collection scan sorted in :ref:`storage order<return-storage-order>`, the
+collection scan sorted in :ref:`natural order<return-natural-order>`, the
 order the database inserts and stores documents on disk.
 
 .. include:: /includes/fact-natural-parameter.rst