(DOCSP-40758): Clarify document order behavior for restores (#162)

* (DOCSP-40758): Clarify document order behavior for restores

* fix include name

* typo

* tweak

* review feedback

* remove unneeded include

* fix duplicate heading

Author: jeff-allen-mongo

source/includes/restore-document-order.rst

@@ -0,0 +1,3 @@
+By default, |tool-binary| may insert documents in a random order. To
+preserve document order during the restore process, use
+|maintain-order-flag|.

source/mongoexport/mongoexport-behavior.txt

@@ -68,4 +68,4 @@ Learn More
 
 - :ref:`mongoexport`
 - :ref:`mongoexport-compatibility-and-installation`
-- :ref:`mongoexport-examples`
+- :ref:`mongoexport-examples`

source/mongoimport/mongoimport-behavior.txt

@@ -47,6 +47,13 @@ formatted using Extended JSON v1.0, specify the
    created from ``mongoexport``, you should use the
    corresponding version of ``mongoimport``.
 
+Document Order
+~~~~~~~~~~~~~~
+
+.. |maintain-order-flag| replace:: :option:`--maintainInsertionOrder <mongoimport --maintainInsertionOrder>`
+
+.. include:: /includes/restore-document-order.rst
+
 Encoding
 ~~~~~~~~
 
@@ -90,4 +97,4 @@ Learn More
 
 - :ref:`mongoimport`
 - :ref:`mongoimport-compatibility-and-installation`
-- :ref:`mongoimport-examples`
+- :ref:`mongoimport-examples`

source/mongorestore/mongorestore-behavior-access-usage.txt

@@ -37,6 +37,13 @@ an existing database and collection and existing documents have the
 same value ``_id`` field as the to-be-restored documents,
 ``mongorestore`` will *not* overwrite those documents.
 
+Document Order
+~~~~~~~~~~~~~~
+
+.. |maintain-order-flag| replace:: :option:`--maintainInsertionOrder <mongorestore --maintainInsertionOrder>`
+
+.. include:: /includes/restore-document-order.rst
+
 Rebuild Indexes
 ~~~~~~~~~~~~~~~
 
@@ -175,4 +182,4 @@ Learn More
 
 - :ref:`mongorestore`
 - :ref:`mongorestore-compatibility-and-installation`
-- :ref:`mongorestore-examples`
+- :ref:`mongorestore-examples`