DOCSP-30350 adding suggestions and API doc links

Author: mballard-mdb

source/crud/bulk.txt

@@ -628,28 +628,16 @@ unordered.
 Troubleshooting
 ---------------
 
-.. include:: /includes/crud/write-error.rst
+If the driver encounters an error during a bulk write operation, the driver
+throws a `MongoBulkWriteException
+<{+core-api+}/MongoBulkWriteException.html>`__. A ``MongoBulkWriteException``
+contains a ``writeErrors`` field consisting of a list of one or more
+``WriteError`` objects associated with the same bulk write operation. 
 
-Bulk Write Exception
-~~~~~~~~~~~~~~~~~~~~
-
-The driver creates a write exception when it creates a ``WriteError`` object. If an
-error is detected during a bulk write operation, the driver throws a `MongoBulkWriteException
-<{+core-api+}/MongoBulkWriteException.html>`__.
-
-A ``MongoBulkWriteException`` contains a ``writeErrors`` field consisting of a
-list of one or more ``WriteError`` objects associated with the same bulk write
-operation. 
-
-Example
-```````
-
-For example, the driver throws a ``MongoBulkWriteException`` if your bulk insert
-contains two documents that violate the collection's schema
-validation rules. Suppose the collection has a rule where the value of the
-``quantity`` field must be an ``int`` type. If your bulk insert contains a
-document with a ``quantity`` of ``"three"`` and another with a ``quantity`` of
-``"ten"``, the driver prints the following error message:
+Consider a collection that has a rule where the value of the ``quantity`` field
+must be an ``int`` type. In the following example, a ``MongoBulkWriteException``
+is thrown when when you attempt to insert a document with a ``quantity`` field
+value of ``"three"`` and another with a ``quantity`` field value of ``"ten"``.
 
 .. code-block:: none
    :copyable: false
@@ -676,15 +664,8 @@ document with a ``quantity`` of ``"three"`` and another with a ``quantity`` of
    com.mongodb.internal.connection.ProtocolHelper.getBulkWriteException(ProtocolHelper.java:254)
    ... 19 more    
 
-
-In the preceding error message, the ``MongoBulkWriteException`` object provides
-a vague description of the error, as documents associated with the same bulk
-operation could produce different error types. Instead, refer to the
-``WriteError`` objects' ``message`` fields to determine the cause of each error.
-Refer to the ``WriteError`` objects' ``details`` field for more specific
-information, such as the schema rules and the offending documents. To address
-this error, you must either revise the document to adhere to the schema
-validation rules or bypass validation.
+To learn more about the ``MongoBulkWriteException`` and ``WriteError`` types,
+see MongoBulkWriteException and WriteError in the API documentation.
 
 Additional Information
 ----------------------
@@ -700,6 +681,7 @@ MongoCollection
 
 - `bulkWrite() <{+driver-api+}/MongoCollection.html#bulkWrite(com.mongodb.client.ClientSession,java.util.List)>`__
 - `BulkWriteOptions <{+core-api+}/client/model/BulkWriteOptions.html>`__
+- `WriteError <{+core-api+}/WriteError.html>`__
 - `MongoBulkWriteException <{+core-api+}/MongoBulkWriteException.html>`__
 
 MongoClient

source/crud/insert.txt

@@ -15,7 +15,7 @@ Insert Operations
 .. contents:: On this page
    :local:
    :backlinks: none
-   :depth: 1
+   :depth: 2
    :class: singlecol
 
 Overview
@@ -194,27 +194,15 @@ operation and an insert many operation:
 Troubleshooting
 ---------------
 
-.. include:: /includes/crud/write-error.rst
+The driver throws a `MongoWriteException
+<{+core-api+}/MongoWriteException.html>`__ for any write errors that occur when
+performing single write operations. A ``MongoWriteException`` object has an
+``error`` field containing the ``WriteError`` object that caused it.
 
-Write Exception
-~~~~~~~~~~~~~~~
-
-The driver creates a write exception when it creates a ``WriteError`` object. The
-driver throws a `MongoWriteException <{+core-api+}/MongoWriteException.html>`__
-for any write errors that occur when performing single write operations.
-
-A ``MongoWriteException`` object has an ``error`` field containing the
-``WriteError`` object that caused it.
-
-Example
-```````
-
-For example, the driver throws a ``MongoWriteException`` if you
-attempt to insert a document into a collection that violates the collection's
-schema validation rules. Suppose the collection has a rule where the value of
-the ``quantity`` field must be an ``int`` type. If you attempt to insert a
-document where the value of ``quantity`` is ``"three"``, the driver prints the
-following error message:
+Consider a collection with a rule where the value of the ``quantity`` field must
+be an ``int`` type. In the following example, a ``MongoBulkWriteException`` is
+thrown if you attempt to insert a document where the value of ``quantity`` is
+``"three"``.
 
 .. code-block:: none
    :copyable: false
@@ -229,13 +217,9 @@ following error message:
    offendingDocument: {"name":"Apple","quantity":"three"} } } at
    com.mongodb.internal.connection.WriteResultHelper.createWriteException(WriteResultHelper.java:50)
 
-In the preceding error message, the ``MongoWriteException`` object provides a
-high-level description of the error. The ``WriteError`` object provides details
-on the failed operation, such as the schema rules and the offending document. To
-address this error, you must either revise the document to adhere to the schema
-validation rules or bypass validation.
-
-To learn more about schema validation, see :manual:`Schema Validation </core/schema-validation/>` in the Server Manual.
+To learn more about the ``MongoWriteException`` and ``WriteError`` types,
+see MongoWriteException and WriteError in the API documentation. To learn
+more about schema validation, see Schema Validation in Additional Information.
 
 Additional Information
 ----------------------
@@ -250,8 +234,14 @@ For more information about the methods and classes used to insert documents, see
 - `insertMany() <{+driver-api+}/MongoCollection.html#insertMany(java.util.List)>`__
 - `InsertManyResult <{+core-api+}/client/result/InsertManyResult.html>`__ 
 
+For more information about the error types discussed in the Troubleshooting section, see the following API documentation: 
+
+- `WriteError <{+core-api+}/WriteError.html>`__
+- `MongoWriteException <{+core-api+}/MongoWriteException.html>`__
+
 Server Manual Entries
 ~~~~~~~~~~~~~~~~~~~~~
 
 - :manual:`db.collection.insertOne() </reference/method/db.collection.insertOne/>`
 - :manual:`db.collection.insertMany() </reference/method/db.collection.insertMany/>`
+- :manual:`Schema Validation </core/schema-validation/>`