DOCS-5167: Move 3.0 dot notation change example out of API reference

source/includes/apiargs-method-db.collection.update-param.yaml

@@ -8,6 +8,8 @@ description: |
 
      .. include:: /includes/fact-mongodb30-upsert-id.rst
 
+     For an example, see :ref:`mongodb30-upsert-id`.
+
 interface: method
 name: query
 operation: db.collection.update

source/includes/fact-mongodb30-upsert-id-example.rst

@@ -0,0 +1,10 @@
+For example, consider the following update operation. Since the update
+operation specifies ``upsert:true`` and the query specifies conditions on the
+``_id`` field using dot notation, then the update will result in an error when
+constructing the document to insert.
+
+.. code-block:: javascript
+
+   db.collection.update( { "_id.name": "Robert Frost", "_id.uid": 0 },
+      { "categories": ["poet", "playwright"] },
+      { upsert: true } )

source/includes/fact-mongodb30-upsert-id.rst

@@ -1,9 +1,9 @@
-When you execute an :method:`~db.collection.update()` with the ``upsert``
-option, you can no longer use :ref:`document-dot-notation` to select only on
-part of the ``_id`` field. For example, the following will raise an error:
+When you execute an :method:`~db.collection.update()` with ``upsert: true`` and
+the query matches no existing document, MongoDB will refuse to insert a new
+document if the query specifies conditions on the ``_id`` field using
+:ref:`dot notation <document-dot-notation>`.
 
-.. code-block:: javascript
+This restriction ensures that the order of fields embedded in the ``_id``
+document is well-defined and not bound to the order specified in the query
 
-   db.collection.update( { "_id.authorID": 1 },
-      { "name": "Robert Frost" },
-      { upsert: true } )
+If you attempt to insert a document in this way, MongoDB will raise an error.

source/reference/method/db.collection.update.txt

@@ -177,6 +177,16 @@ The remaining operations would either:
   applications may retry the operation which will succeed as an update
   operation.
 
+.. _mongodb30-upsert-id:
+
+``upsert:true`` with a Dotted ``_id`` Query
+```````````````````````````````````````````
+
+.. include:: /includes/fact-mongodb30-upsert-id.rst
+
+.. include:: /includes/fact-mongodb30-upsert-id-example.rst
+
+
 .. _multi-parameter:
 
 Multi Parameter

source/release-notes/3.0-compatibility.txt

@@ -458,6 +458,8 @@ General Compatibility Changes
 
 .. include:: /includes/fact-mongodb30-upsert-id.rst
 
+.. include:: /includes/fact-mongodb30-upsert-id-example.rst
+
 Deprecate Access to ``system.indexes`` and ``system.namespaces``
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~