DOCSP-13854 usage examples landing page (#22)

* added usage examples landing page

Author: kyuan-mongodb

snooty.toml

@@ -3,7 +3,7 @@ title = "Go"
 toc_landing_pages = [
     "/fundamentals/connection",
     "/fundamentals/crud",
-    "/fundamentals/builders"
+    "/usage-examples"
 ]
 
 [constants]

source/usage-examples.txt

@@ -4,6 +4,12 @@ Usage Examples
 
 .. default-domain:: mongodb
 
+.. contents:: On this page
+   :local:
+   :backlinks: none
+   :depth: 1
+   :class: singlecol
+
 .. toctree::
 
    /usage-examples/find-operations
@@ -23,47 +29,67 @@ 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
+operations. Each example provides the following:
 
-- an explanation of how to use the operation, including parameters,
-  return values, and common exceptions you might encounter
-
-- a full Go program that you can copy and paste to run the example
-  in your own environment
+- A full Go program that you can run in your own environment
+- The expected result after running the program
 
 How to Use the Usage Examples
 -----------------------------
 
 These examples use the :atlas:`sample datasets <sample-data>` provided by
 Atlas. You can load them into your database on the free tier of MongoDB
-Atlas by following the
-:atlas:`Get Started with Atlas Guide <getting-started/#atlas-getting-started>`
-or you can
+Atlas by following the :atlas:`Get Started with Atlas Guide
+<getting-started/#atlas-getting-started>` or you can
 :guides:`import the sample dataset into a local MongoDB instance
 </server/import/>`.
 
-Once you have imported the dataset, you can copy and paste a usage
+Once you import 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 the MongoDB Go Driver. Once you've copied a usage example,
-you'll need to edit the connection string to get the example connected to
-your instance of MongoDB:
+started with the MongoDB Go Driver. 
+
+To connect the example to your MongoDB instance, you must :ref:`define
+an environment variable <usage-examples-env-variable>` with
+:ref:`your connection string <usage-examples-connection-string>`. 
 
 .. code-block:: go
+   
+   uri := os.Getenv("MONGODB_URI")
+
+.. _usage-examples-env-variable:
+
+Environment Variable
+~~~~~~~~~~~~~~~~~~~~
+
+You can use `GoDotEnv <https://github.com/joho/godotenv>`__ to define
+your environment variable. 
+
+Add the following application configuration in your ``.env`` file at the
+root of your project. For more information, see the
+`GoDotEnv documentation <https://github.com/joho/godotenv#usage>`__.
 
-   // Replace the following with your MongoDB deployment's connection string.
-   uri := "mongodb+srv://<user>:<password>@<cluster-url>?retryWrites=true&w=majority";
+.. code-block::
+
+   MONGODB_URI=mongodb+srv://<user>:<password>@<cluster-url>?retryWrites=true&w=majority
+
+.. note::
+
+   Replace the preceding connection string with :ref:`your MongoDB deployment's connection string <usage-examples-connection-string>`.
+
+.. _usage-examples-connection-string:
+
+Connection String
+~~~~~~~~~~~~~~~~~
 
 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.
-
-For more information about connecting to your MongoDB instance, see the
-Connection Guide.
+to enable connectivity to your Atlas instance and find the
+:manual:`connection string </reference/connection-string/>` to define your
+``MONGODB_URI`` environment variable to run our usage examples. 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. 
+
+For more information about connecting to your MongoDB instance, see our
+<TODO: Connection Guide>.
+