DOCSP-9047: TOC landing pages (#72)

* DOCSP-9047: Update ToC landing pages

Author: Chris Cho

snooty.toml

@@ -1,4 +1,7 @@
 name = "node"
+title = "NodeJS"
+
+toc_landing_pages = ["/fundamentals/authentication", "/fundamentals/crud", "/usage-examples"]
 
 [constants]
 version = 4.0

source/faq.txt

@@ -24,13 +24,13 @@ What Is the Difference Between "connectTimeoutMS", "socketTimeoutMS" and "maxTim
      - Description
    * - connectTimeoutMS
      - 30000
-     - ``connectTimeoutMS`` is a `connection-setting <https://mongodb.github.io/node-mongodb-native/3.5/reference/connecting/connection-settings/>`_ option that sets the time in milliseconds to establish a connection to the MongoDB server before timing out. 
+     - ``connectTimeoutMS`` is a `connection-setting <https://mongodb.github.io/node-mongodb-native/3.5/reference/connecting/connection-settings/>`_ option that sets the time in milliseconds to establish a connection to the MongoDB server before timing out.
    * - socketTimeoutMS
      - 360000
      - ``socketTimeoutMS`` is a ``connection-settings`` option that sets the number of milliseconds a socket stays inactive after the driver has successfully connected before closing the connection.
    * - maxTimeMS
      - N/A
-     - :node-api:`maxTimeMS() </Cursor.html#maxTimeMS>` is a :manual:`cursor method </reference/method/js-cursor>` that specifies the max time limit for processing an operation on a cursor. If an operation runs over the time allotted it will return a timeout error.  
+     - :node-api:`maxTimeMS() </Cursor.html#maxTimeMS>` is a :manual:`cursor method </reference/method/js-cursor>` that specifies the max time limit for processing an operation on a cursor. If an operation runs over the time allotted it will return a timeout error.
 
 How Can I Prevent the Driver From Hanging During Connection or From Spending Too Long Trying to Reach Unreachable Replica Sets?
 -------------------------------------------------------------------------------------------------------------------------------
@@ -62,10 +62,10 @@ continue to run on the MongoDB server, which could cause data
 inconsistencies if the application retries the operation on failure.
 
 However, there are important use cases for ``socketTimeoutMS`` -
-consider the following cases: 
+consider the following cases:
 
-- A MongoDB process erroring out 
-- A misconfigured firewall causing a socket connection without sending a ``FIN`` packet 
+- A MongoDB process erroring out
+- A misconfigured firewall causing a socket connection without sending a ``FIN`` packet
 
 In those cases, there is no way to detect that the connection has died.
 Setting the ``socketTimeoutMS`` is essential to ensure that the sockets
@@ -76,18 +76,18 @@ through the driver.
 How Can I Prevent Sockets From Timing out Before They Become Active?
 --------------------------------------------------------------------
 Having a large connection pool does not always reduce reconnection
-requests.  Consider the following example: 
+requests.  Consider the following example:
 
 An application has a connection pool size of 5 sockets and has the
 ``socketTimeoutMS`` option set to 5000 milliseconds. Operations occur,
 on average, every 3000 milliseconds, and reconnection requests are
 frequent. Each socket times out after 5000 milliseconds, which means
 that all sockets must do something during those 5000 milliseconds to
-avoid closing. 
+avoid closing.
 
 One message every 3000 milliseconds is not enough to keep the sockets
 active, so several of the sockets will time out after 5000 milliseconds.
-Reduce the ``poolSize`` in the connection settings to fix the problem. 
+Reduce the ``poolSize`` in the connection settings to fix the problem.
 
 What Does a Value of "0" mean for "connectTimeoutMS" and "socketTimeoutMS"?
 ---------------------------------------------------------------------------
@@ -100,7 +100,7 @@ How Can I Prevent Long-Running Operations From Slowing Down the Server?
 
 By using ``maxTimeMS()`` you can prevent long-running operations from
 slowing down the server. This method allows the MongoDB server to cancel
-operations that run for more than the set value of ``maxTimeMS``.  
+operations that run for more than the set value of ``maxTimeMS``.
 
 The following example demonstrates how to use MaxTimeMS with a find
 operation:
@@ -125,12 +125,12 @@ What Can I Do If I'm Experiencing Unexpected Network Behavior?
 --------------------------------------------------------------
 Internal firewalls that exist between application servers and MongoDB
 are often misconfigured and are overly aggressive in their removal of
-socket connections. 
+socket connections.
 
 If you experience unexpected network behavior, here
 are some things to check:
 
-#. The firewall should send a ``FIN packet`` when closing a socket,allowing the driver to detect that the socket is closed. 
+#. The firewall should send a ``FIN packet`` when closing a socket,allowing the driver to detect that the socket is closed.
 #. The firewall should allow ``keepAlive`` probes.
 
 What Can I Do If I'm Getting "ECONNRESET" When Calling "client.connect()"?
@@ -153,7 +153,7 @@ If this operation causes an ``ECONNRESET`` error, you may have run into
 the ``file descriptor`` limit for your Node.js process. In that case you
 must increase the number of ``file descriptors`` for the Node.js process. On
 MacOS and Linux you do this with the `ulimit
-<https://ss64.com/bash/ulimit.html>`_ shell command. 
+<https://ss64.com/bash/ulimit.html>`_ shell command.
 
 .. code-block:: sh
 
@@ -178,36 +178,36 @@ other, faster operations.
 
 .. note::
     If the number of operations is greater than the set ``poolSize`` and
-    a slow operation occurs, subsequent operations will be delayed. 
+    a slow operation occurs, subsequent operations will be delayed.
 
 How Can I Ensure My Connection String Is Valid for a Replica Set?
 -----------------------------------------------------------------
 
 The connection string passed to the driver must use exact hostnames for
-the servers as set in the :manual:`Replica Set Config </reference/replica-configuration/>`. 
-Given the following configuration settings for your `Replica Set`, in
-order for the `Replica Set` discovery and :manual:`failover
+the servers as set in the :manual:`Replica Set Config </reference/replica-configuration/>`.
+Given the following configuration settings for your Replica Set, in
+order for the Replica Set discovery and :manual:`failover
 </reference/glossary/#term-failover>` to work the driver should be able
-to reach ``server1``, ``server2``, and ``server3``. 
-
-  .. code-block:: JSON
-
-    {
-      "_id": "testSet",
-      "version": 1,
-      "protocolVersion": 1,
-      "members": [
-        {
-          "_id": 1,
-          "host": "server1:31000"
-        },
-        {
-          "_id": 2,
-          "host": "server2:31001"
-        },
-        {
-          "_id": 3,
-          "host": "server3:31002"
-        }
-      ]
-    }
+to reach ``server1``, ``server2``, and ``server3``.
+
+.. code-block:: JSON
+
+   {
+     "_id": "testSet",
+     "version": 1,
+     "protocolVersion": 1,
+     "members": [
+       {
+         "_id": 1,
+         "host": "server1:31000"
+       },
+       {
+         "_id": 2,
+         "host": "server2:31001"
+       },
+       {
+         "_id": 3,
+         "host": "server3:31002"
+       }
+     ]
+   }

source/fundamentals/crud.txt

@@ -16,19 +16,20 @@ Overview
 --------
 
 CRUD (Create, Read, Update, Delete) operations allow you to work with
-the data stored inside of MongoDB. CRUD operations fall into two
-categories: `read operations <crud-read-operations>`_ and
-`write operations <crud-write-operations>`_.
+the data stored inside of MongoDB. We categorized the CRUD operations into
+two sections: :ref:`crud-read-operations` and :ref:`crud-write-operations`.
 
 .. note::
 
    CRUD operations execute **asynchronously** because the driver
    communicates with MongoDB over the network, which is subject to
    latency, timeouts, and other complications that can delay execution
-   during synchronous communication. As a result, each CRUD
-   method returns a Promise that resolves to the output of that
-   operation. A common method of Promise resolution uses
-   ``async``/``await`` syntax.
+   during synchronous communication. You can specify a callback in the
+   CRUD method call to capture the response. If you do not specify a
+   callback, the operation returns a
+   :mdn:`Promise <Web/JavaScript/Reference/Global_Objects/Promise>` that
+   resolves to the output of the operation. We use the ``async``/``await``
+   syntax for Promise resolution in our examples.
 
 .. _crud-read-operations:
 

source/fundamentals/crud/read-operations/text.txt

@@ -17,7 +17,7 @@ words or phrases, instead of matching substrings like
 :mdn:`regular expressions
 <Web/JavaScript/Guide/Regular_Expressions>`,
 also known as RegEx. While regex is very powerful, and MongoDB even
-offers a `$regex <>` operator, text searches work particularly well when
+offers a ``$regex`` operator, text searches work particularly well when
 applied to unstructured text, like transcripts, essays, or even web
 pages. Because MongoDB's text indexes are aware of concepts like
 plurality, case sensitivity, stop words, whitespace, and punctuation in

source/index.txt

@@ -78,13 +78,13 @@ material on using the Node.js driver for the following:
 
 Usage Examples
 --------------
-The :doc:`Usage Examples </usage-examples/overview>` section provides
+The :doc:`Usage Examples </usage-examples>` section provides
 runnable code snippets and explanations for common methods. We recommend
 this section for users that are new to the MongoDB Node.js driver.
 
 API
 ---
-See the :doc:`API </api-documentation/>` section if you are looking for
+See the :node-api:`API documentation <>` if you are looking for
 technical information about classes, methods, and configuration objects
 within the MongoDB Node.js driver.
 

source/quick-start.txt

@@ -196,4 +196,4 @@ Next Steps
 
 Learn how to read and modify data in our :doc:`CRUD fundamentals
 </fundamentals/crud>` guide, or how to perform common operations in our
-:doc:`usage examples </usage-examples/overview>`.
+:doc:`usage examples </usage-examples>`.

source/tutorials.txt

@@ -4,25 +4,8 @@ Usage Examples
 
 .. default-domain:: mongodb
 
-:doc:`bulkWrite </usage-examples/bulkWrite>`
-:doc:`countDocuments and estimatedDocumentCount </usage-examples/count>`
-:doc:`deleteMany </usage-examples/deleteMany>`
-:doc:`insertOne </usage-examples/insertOne>`
-:doc:`deleteOne </usage-examples/deleteOne>`
-:doc:`find </usage-examples/find>`
-:doc:`findOne </usage-examples/findOne>`
-:doc:`insertMany </usage-examples/insertMany>`
-:doc:`updateOne</usage-examples/updateOne>`
-:doc:`updateMany</usage-examples/updateMany>`
-:doc:`replaceOne</usage-examples/replaceOne>`
-:doc:`distinct</usage-examples/distinct>`
-:doc:`command</usage-examples/command>`
-:doc:`changeStream</usage-examples/changeStream>`
-
 .. toctree::
-   :caption: Examples
 
-   /usage-examples/overview
    /usage-examples/find-operations
    /usage-examples/insert-operations
    /usage-examples/update-and-replace-operations
@@ -32,3 +15,52 @@ Usage Examples
    /usage-examples/command
    /usage-examples/changeStream
    /usage-examples/bulkWrite
+
+Overview
+--------
+
+Usage examples provide convenient starting points for popular MongoDB
+operations. Each example provides:
+
+- an explanation of the operation in the example showing the
+  purpose and a sample use case for the method
+
+- an explanation of how to use the operation, including parameters,
+  return values, and common exceptions you might encounter
+
+- a full Node.js program that you can copy and paste to run the example
+  in your own environment
+
+How to Use the Usage Examples
+-----------------------------
+
+These examples use the :atlas:`MongoDB Atlas sample data <sample-data>`
+database. You can use this sample data on the free tier
+of MongoDB Atlas by following the :atlas:`Get Started with Atlas
+<getting-started/#atlas-getting-started>` guide or you can
+:manual:`import the sample dataset into a local MongoDB instance
+</import/>`.
+
+Once you have imported the dataset, you can copy and paste a usage
+example into your development environment of choice. You can follow the
+:doc:`quick start guide </quick-start>` to learn more about getting
+started with Node.js, npm, and the Node.js driver. Once you've copied
+a usage example, you'll have to edit one line to get the example running
+with your instance of MongoDB:
+
+.. code-block:: javascript
+
+   // Replace the following with your MongoDB deployment's connection string.
+   const uri =
+      "mongodb+srv://<user>:<password>@<cluster-url>?retryWrites=true&w=majority";
+
+You can use the :guides:`Atlas Connectivity Guide
+</cloud/connectionstring/>` to enable connectivity to your instance of
+Atlas and find the :manual:`connection string
+</reference/connection-string/>` to replace the ``uri`` variable in the
+usage example. If your instance uses :manual:`SCRAM authentication
+</core/security-scram/>`, you can replace ``<user>`` with your username,
+``<password>`` with your password, and ``<cluster-url>`` with the IP
+address or URL of your instance. Consult the 
+:doc:`Connection Guide </fundamentals/connection>` for more information 
+about getting connected to your MongoDB instance.