(DOCSP-13713): Improve layout of connect page (#243)

* WIP

* WIP

* (DOCSP-13713): Improve layout of connect page

* wording

* add option links

* fix rst formatting

* add note heading

* capitalization

* minimalism

* minimalism

* review edits and fixes

* task-ify title

* tweaks

* punctuation

* wording

* wording

* Update source/connect.txt

Co-authored-by: Anna Henningsen <[email protected]>

* readd --password note and small edits

* punctuation

* add clarifying sentence about drivers

* fix build warning

Co-authored-by: Anna Henningsen <[email protected]>

Author: jeff-allen-mongo

source/connect.txt

@@ -21,12 +21,11 @@ Prerequisites
 .. include:: /includes/fact-connect-prereqs.rst
 
 
-Local MongoDB Instance on Default Port
---------------------------------------
+Connect to a Local Deployment on the Default Port
+-------------------------------------------------
 
-Run ``mongosh`` without any command-line options
-to connect to a MongoDB instance running on your **localhost** with 
-**default port** 27017:
+To connect to a MongoDB deployment running on **localhost** with
+**default port** 27017, run ``mongosh`` without any options:
 
 .. code-block:: sh
 
@@ -38,204 +37,207 @@ This is equivalent to the following command:
 
    mongosh "mongodb://localhost:27017"
 
-Local MongoDB Instance on a Non-Default Port
---------------------------------------------
+Connect to a Local Deployment on a Non-Default Port
+---------------------------------------------------
 
-To specify a port to connect to on localhost, you can use:
+To specify a port to connect to on localhost, you can use either:
 
-- A :manual:`connection string </reference/connection-string>`. 
+- A :manual:`connection string </reference/connection-string>` with the
+  chosen port
 
-  .. example::
-  
-     To connect to a MongoDB instance running on localhost with a 
-     non-default port 28015:
-  
-     .. code-block:: sh
-  
-        mongosh "mongodb://localhost:28015"
+- The ``--port`` command-line option
 
-- The command-line option ``--port``.
+For example, the following commands connect to a deployment running on
+localhost port 28015:
 
-  .. example:: 
-
-     To connect to a MongoDB instance running on localhost with a 
-     non-default port 28015:
+.. code-block:: sh
 
-     .. code-block:: sh
+   mongosh "mongodb://localhost:28015"
 
-        mongosh --port 28015
+.. code-block:: sh
 
-MongoDB Instance on a Remote Host
----------------------------------
+   mongosh --port 28015
 
-To specify a remote host and port, you can use:
+Connect to a Deployment on a Remote Host
+----------------------------------------
 
-- A :manual:`connection string </reference/connection-string>`.
+To specify a remote host and port, you can use either:
 
-  .. example:: 
+- A :manual:`connection string </reference/connection-string>` with the
+  chosen host and port.
 
-     To connect to a MongoDB
-     instance running on a remote host on port 28015:
+- The ``--host`` and ``--port`` command-line options. If you omit the
+  ``--port`` option, ``mongosh`` uses the default port 27017.
 
-     .. code-block:: sh
+For example, the following commands connect to a MongoDB deployment
+running on host ``mongodb0.example.com`` and port 28015:
 
-        mongosh "mongodb://mongodb0.example.com:28015"
+.. code-block:: sh
 
-  .. note:: Connecting to |service|
-  
-     If your remote host is a |service-fullname| cluster, you can copy 
-     your connection string from the |service| UI. To learn more, see 
-     :atlas:`Connect to a Cluster </connect-to-cluster/#use-the-connect-dialog-to-connect-to-your-cluster>`.
+   mongosh "mongodb://mongodb0.example.com:28015"
 
-- The command-line options ``--host`` and ``--port``. If you do not 
-  include the ``--port`` option, ``mongosh`` uses the **default port** 
-  27017.
+.. code-block:: sh
 
-  .. example:: 
+   mongosh --host mongodb0.example.com --port 28015
 
-     To connect to a MongoDB
-     instance running on a remote host on port 28015:
+.. note:: Connect to |service-fullname|
 
-     .. code-block:: sh
+   If your remote host is an |service| cluster, you can copy your
+   connection string from the |service| UI. To learn more, see
+   :atlas:`Connect to a Cluster
+   </connect-to-cluster/#use-the-connect-dialog-to-connect-to-your-cluster>`
+   in the Atlas documentation.
 
-        mongosh --host mongodb0.example.com --port 28015
+Specify Connection Options
+--------------------------
 
-Connection Options
-------------------
+Specify different connection options to connect to different types of
+deployments.
 
-Connect with Authentication
+Connect With Authentication
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-To connect to a MongoDB instance requires authentication, use the 
-``--username`` and ``--authenticationDatabase`` command-line options. 
-``mongosh`` prompts you for a password, which it masks as you type.
-  
-.. example:: 
-
-   To connect to a remote MongoDB instance and authenticate against 
-   the ``admin`` database as user ``alice``:
-
-   .. code-block:: sh
+To connect to a MongoDB deployment that requires authentication, use the
+:option:`--username <--username>` and :option:`--authenticationDatabase
+<--authenticationDatabase>` options. ``mongosh`` prompts you for a
+password, which it hides as you type.
 
-      mongosh "mongodb://mongodb0.example.com:28015" --username alice --authenticationDatabase admin
+For example, to authenticate as user ``alice`` on the ``admin``
+database, run the following command:
 
-.. note::
+.. code-block:: sh
 
-   To provide a password with the command instead of using the masked 
-   prompt, you can use the ``--password`` option.
+   mongosh "mongodb://mongodb0.example.com:28015" --username alice --authenticationDatabase admin
+   
+To provide a password as part of the connection command instead of using
+the prompt, use the :option:`--password <--password>` option. Use this
+option for programmatic usage of ``mongosh``, like a :driver:`driver
+</>`.
 
 .. seealso::
 
-   - :manual:`Enable Access Control </tutorial/enable-authentication/>` 
-     to enforce authentication.
-   - Add :manual:`Database Users </core/security-users/>` 
-     to provide authenticated access to a MongoDB instance.
+   - To enforce authentication on a deployment, see
+     :manual:`Enable Access Control </tutorial/enable-authentication/>`.
+
+   - To provision access to a MongoDB deployment, see :manual:`Database
+     Users </core/security-users/>`.
 
 Connect to a Replica Set
 ~~~~~~~~~~~~~~~~~~~~~~~~
 
-To connect to a replica set:
+To connect to a replica set, you can either: 
+
+- Use the :manual:`DNS Seedlist Connection Format
+  </reference/connection-string/#dns-seedlist-connection-format>`.
 
-- If you are using the :manual:`DNS Seedlist Connection Format 
-  </reference/connection-string/#dns-seedlist-connection-format>`, you 
-  can include the ``+srv`` modifier in your connection string.
+- Explicitly specify the replica set name and members in the connection
+  string.
 
-  .. example::
+Option 1: DNS Seedlist Format
+`````````````````````````````
 
-     .. code-block:: sh
+To use the DNS seedlist connection format, include the ``+srv`` modifier
+in your connection string.
 
-        mongosh "mongodb+srv://server.example.com/"
+For example, to connect to a replica set on ``server.example.com``, run
+the following command:
 
-  .. note::
-     Using the ``+srv`` connection string modifier automatically sets 
-     the 
-     :manual:`tls option </reference/connection-string/#urioption.tls>` 
-     to ``true`` for the connection. You can 
-     override this behavior by explicitly setting ``tls`` to ``false``.
+.. code-block:: sh
+
+   mongosh "mongodb+srv://server.example.com/"
 
-- You can specify the replica set name and members in the
-  :manual:`connection string </reference/connection-string>`.
+.. note:: +srv TLS Behavior
 
-  .. example::
+   When you use the ``+srv`` connection string modifier, MongoDB
+   automatically sets the :option:`--tls <--tls>` connection option to
+   ``true``. To override this behavior, set ``--tls`` to ``false``.
 
-     To connect to a three-member replica set named ``replA``:
+Option 2: Specify Members in Connection String
+``````````````````````````````````````````````
 
-     .. code-block:: sh
+You can specify individual replica set members in the
+:manual:`connection string </reference/connection-string>`.
 
-        mongosh "mongodb://mongodb0.example.com.local:27017,mongodb1.example.com.local:27017,mongodb2.example.com.local:27017/?replicaSet=replA"
+For example, to connect to a three-member replica set named ``replA``,
+run the following command:
 
-.. note::
+.. code-block:: sh
+
+   mongosh "mongodb://mongodb0.example.com.local:27017,mongodb1.example.com.local:27017,mongodb2.example.com.local:27017/?replicaSet=replA"
+   
+.. note:: directConnection Parameter Added Automatically
 
-   ``mongosh`` adds the ``directConnection=true`` query parameter to the
-   connection string automatically unless at least one of the following is
-   true:
+   When you specify individual replica set members in the connection
+   string, ``mongosh`` automatically adds the ``directConnection=true``
+   parameter, unless at least one of the following is true:
 
    - The ``replicaSet`` query parameter is present in the connection string.
-   - The connection string uses the ``mongodb+srv://`` scheme.
+   - The connection string uses the ``mongodb+srv://`` connection string
+     format.
    - The connection string contains a seed list with multiple hosts.
+   - The connection string already contains a ``directConnection``
+     parameter.
 
-Connect using TLS
+   When ``directConnection=true``, all operations are run on the host
+   specified in the connection URI.
+
+Connect Using TLS
 ~~~~~~~~~~~~~~~~~
 
-For ``tls`` connections:
+To connect to a deployment using TLS, you can either:
 
-- If you are using the :manual:`DNS Seedlist Connection Format 
-  </reference/connection-string/#dns-seedlist-connection-format>`, the 
-  ``+srv`` connection string modifier automatically sets
-  the ``tls`` option to ``true`` for the connection:
+- Use the :manual:`DNS Seedlist Connection Format
+  </reference/connection-string/#dns-seedlist-connection-format>`. The
+  ``+srv`` connection string modifier automatically sets the ``tls``
+  option to ``true`` for the connection.
 
-  .. example::
+  For example, to connect to a DNS seedlist-defined replica set with
+  ``tls`` enabled, run the following command:
 
-     To connect to a DNS seedlist-defined replica set with ``tls`` 
-     enabled:
+  .. code-block:: sh
 
-     .. code-block:: sh
+     mongosh "mongodb+srv://server.example.com/"
 
-        mongosh "mongodb+srv://server.example.com/"
+- Set the :option:`--tls <--tls>` option to ``true`` in the connection
+  string.
 
-- You can use the 
-  :manual:`tls option </reference/connection-string/#urioption.tls>` to 
-  set ``tls=true`` in the 
-  :manual:`connection string </reference/connection-string>`:
+  For example, to enable ``tls`` with a connection string option, run
+  the following command:
 
-  .. example::
+  .. code-block:: sh
 
-     To enable ``tls`` in the connection string:
+     mongosh "mongodb://mongodb0.example.com:28015/?tls=true"
 
-     .. code-block:: sh
+- Specify the ``--tls`` command-line option.
 
-        mongosh "mongodb://mongodb0.example.com:28015/?tls=true"
+  For example, to connect to a remote host with ``tls`` enabled, run the
+  following command:
 
-- You can specify the ``--tls`` command-line option.
-  
-  .. example:: 
-     
-     To connect to a remote host with ``tls`` enabled:
-
-     .. code-block:: sh
+  .. code-block:: sh
 
-        mongosh "mongodb://mongodb0.example.com:28015" --tls
+     mongosh "mongodb://mongodb0.example.com:28015" --tls
 
 Connect to a Specific Database
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 To connect to a specific database, specify a database in your
-:manual:`connection string URI path </reference/connection-string/>` If
-you do not specify a database in your URI path, you connect to a database named ``test``.
+:manual:`connection string URI path </reference/connection-string/>`. If
+you do not specify a database in your URI path, you connect to the
+``test`` database.
 
-.. example::
+For example, to connect to a database called ``qa`` on localhost, run the
+following command:
 
-  The following connection string URI connects to database ``db1``.
-
-  .. code-block:: sh
+.. code-block:: sh
 
-      mongosh "mongodb://localhost:27017/db1" 
+    mongosh "mongodb://localhost:27017/qa" 
 
 Connect to a Different Deployment
 ---------------------------------
 
-You can use the :method:`Mongo()` or the :manual:`connect()
-</reference/method/connect/>` methods to connect to a different MongoDB
+If you are already connected to a deployment in the |mdb-shell|, you can
+use the :method:`Mongo()` or :manual:`connect()
+</reference/method/connect/>` method to connect to a different
 deployment from within the |mdb-shell|.
 
 To learn how to connect to a different deployment using these methods,
@@ -244,17 +246,17 @@ see :ref:`mdb-shell-open-new-connections-in-shell`.
 Verify Current Connection
 -------------------------
 
-Use the :method:`db.getMongo()` method to verify your current database
-connection.
+To verify your current database connection, use the
+:method:`db.getMongo()` method.
 
-The method returns the
-:manual:`connection string URI </reference/connection-string/>` for
-your current connection.
+The method returns the :manual:`connection string URI
+</reference/connection-string/>` for your current connection.
 
 Disconnect from a Deployment
 ----------------------------
 
-To disconnect from a deployment and exit ``mongosh``, you can:
+To disconnect from a deployment and exit ``mongosh``, perform one of the
+following actions:
 
 - Type ``.exit``, ``exit``, or ``exit()``.
 
@@ -267,17 +269,17 @@ To disconnect from a deployment and exit ``mongosh``, you can:
 Limitations
 -----------
 
-- :manual:`Kerberos authentication </core/kerberos/>` does not permit
+- :manual:`Kerberos authentication </core/kerberos/>` does not allow
   ``authMechanismProperties=CANONICALIZE_HOST_NAME:true|false`` in the
-  connection string. Use one of:
-  ``authMechanismProperties=CANONICALIZE_HOST_NAME:forward|forwardAndReverse|none``
-  instead.
+  connection string. Instead, use either:
+  
+  - ``authMechanismProperties=CANONICALIZE_HOST_NAME:forward``
+  - ``authMechanismProperties=CANONICALIZE_HOST_NAME:forwardAndReverse``
+  - ``authMechanismProperties=CANONICALIZE_HOST_NAME:none``
 
 - ``mongosh`` currently only supports the ``zlib``
   :manual:`compressor </core/wiredtiger/#compression>`. The following 
   compressors are not supported:
 
   - ``zstd``
   - ``snappy``
-
-