DOCSP-48322: BSON tech feedback

source/data-formats/bson.txt

@@ -25,6 +25,39 @@ binary data. You can use BSON documents in your {+language+} application by incl
 `bson <{+api-root+}bson/index.html>`__ package. For a complete list of supported types, see the
 :manual:`BSON Types </reference/bson-types>` server manual page.
 
+BSON documents are stored in MongoDB collections in binary format, while {+driver-short+}
+represents BSON documents as {+language+} dictionaries. {+driver-short+} automatically
+converts {+language+} dictionaries into BSON documents when inserting them into a collection.
+Likewise, when you retrieve a document from a collection, {+driver-short+} converts the BSON
+document back into a {+language+} dictionary.
+
+The following example shows a document in both dictionary and BSON formats. Use the
+:guilabel:`Dictionary` or :guilabel:`BSON` tab to see the corresponding format:
+
+.. tabs::
+
+   .. tab:: Dictionary
+      :tabid: dict
+
+      .. code-block:: python
+
+         {"hello": "world"}
+
+   .. tab:: BSON
+      :tabid: bson
+
+      .. code-block:: none
+
+         \x16\x00\x00\x00           # total document size
+         \x02                       # 0x02 = type String
+         hello\x00                  # field name
+         \x06\x00\x00\x00world\x00  # field value
+         \x00                       # 0x00 = type EOO ("end of object")
+
+
+Sample Data
+~~~~~~~~~~~
+
 The code samples in this guide use the following BSON document as an example:
 
 .. code-block:: none
@@ -43,10 +76,7 @@ Create a BSON Document
 ----------------------
 
 You can create a BSON document by using the same notation you use to create a
-dictionary in {+language+}. {+driver-short+} automatically converts {+language+} dictionaries
-into BSON documents when inserting them into a collection.
-
-The following example creates a BSON document that
+dictionary in {+language+}. The following example creates a BSON document that
 represents the preceding sample BSON document:
 
 .. code-block:: python
@@ -65,7 +95,7 @@ Change a BSON Document
 ----------------------
 
 You can modify the contents of a BSON document by using the same notation you use to modify
-a dictionary in {+language+}. The following example makes three changes to the previous
+a dictionary in {+language+}. The following example makes three changes to the sample
 BSON document:
 
 1. Adds a new field, ``restaurant_id``, with the value ``12345``