DOCSP-36113: add serialization pkgs to quickstart (#150)

* DOCSP-36113: add serialization pkgs to quickstart

* vale and comment

* small fixes

* update rest of QS

* vale

* JS PR fixes 1

Author: rustagir

source/fundamentals.txt

@@ -1,3 +1,5 @@
+.. _kotlin-fundamentals-landing:
+
 ============
 Fundamentals
 ============

source/includes/serialization-libs-gradle-versioned.rst

@@ -0,0 +1,8 @@
+.. code-block:: kotlin
+   :caption: build.gradle.kts
+   :copyable: true
+
+   implementation("org.mongodb:bson-kotlinx:{+full-version+}")
+   // OR
+   implementation("org.mongodb:bson-kotlin:{+full-version+}")
+   

source/includes/serialization-libs-maven-versioned.rst

@@ -0,0 +1,16 @@
+.. code-block:: xml
+   :caption: pom.xml
+   :copyable: true
+
+   <dependency>
+       <groupId>org.mongodb</groupId>
+       <artifactId>bson-kotlinx</artifactId>
+       <version>{+full-version+}</version>
+   </dependency>
+   <!--OR-->
+   <dependency>
+       <groupId>org.mongodb</groupId>
+       <artifactId>bson-kotlin</artifactId>
+       <version>{+full-version+}</version>
+   </dependency>
+  

source/quick-start.txt

@@ -4,6 +4,13 @@
 Quick Start
 ===========
 
+.. facet::
+   :name: genre
+   :values: tutorial
+
+.. meta::
+   :keywords: code example, get started, runnable app
+
 .. contents:: On this page
    :local:
    :backlinks: none
@@ -13,112 +20,146 @@ Quick Start
 Introduction
 ------------
 
-This guide shows you how to create an application that uses the **Kotlin driver**
-to connect to a **MongoDB Atlas cluster**. If you prefer to connect to MongoDB
-using a different driver or programming language, see our
+This guide shows you how to create an application that uses the **{+driver-short+}**
+to connect to a **MongoDB Atlas cluster**. If you prefer to connect to
+MongoDB by using a different driver or programming language, see the
 :driver:`list of official MongoDB drivers <>`.
 
-The Kotlin driver lets you connect to and communicate with MongoDB clusters
+The {+driver-short+} lets you connect to and communicate with MongoDB clusters
 from a Kotlin application.
 
-MongoDB Atlas is a fully-managed cloud database service that hosts your data
-on MongoDB clusters. In this guide, we show you how to get started with your
-own free (no credit card required) cluster.
+MongoDB Atlas is a fully managed cloud database service that hosts your data
+on MongoDB clusters. In this guide, you can learn how to get started with your
+own free cluster.
 
 .. tip::
 
-   For an additional example of how to build an application in Kotlin using 
-   MongoDB Atlas and the {+driver-long+}, see the
+   To view another example that demonstrates how to build an
+   application in Kotlin that connects to MongoDB Atlas, see the
    :website:`Getting Started with the {+driver-long+}
-   </developer/products/mongodb/getting-started-kotlin-driver/>` developer tutorial.
-
-Consult the following steps to connect your Kotlin application with a MongoDB Atlas
-cluster.
+   </developer/products/mongodb/getting-started-kotlin-driver/>`
+   developer tutorial.
 
 Set up Your Project
 -------------------
 
 Install Kotlin
 ~~~~~~~~~~~~~~
 
-Make sure that your system has Kotlin installed running on JDK 1.8 or later.
+Make sure that your system has Kotlin installed and running on JDK 1.8 or later.
 For more information on getting started with Kotlin/JVM development,
 refer to `Get started with Kotlin/JVM <{+kotlin-docs+}/jvm-get-started.html>`__
 in the Kotlin language documentation.
 
 Create the Project
 ~~~~~~~~~~~~~~~~~~~
 
-This guide shows you how to add the MongoDB Kotlin driver dependencies using
-Gradle or Maven. We recommend that you use an integrated development
-environment (IDE) such as Intellij IDEA or Eclipse IDE to make it more convenient
-to configure Gradle or Maven to build and run your project.
+This guide shows you how to add the MongoDB Kotlin driver dependencies
+by using Gradle or Maven. We recommend that you use an integrated development
+environment (IDE) such as IntelliJ IDEA or Eclipse IDE to configure
+Gradle or Maven to build and run your project.
 
-If you are not using an IDE, see
-`Creating New Gradle Builds <https://guides.gradle.org/creating-new-gradle-builds/>`_
-or  `Building Maven <https://maven.apache.org/guides/development/guide-building-maven.html>`_
+If you are not using an IDE, see the
+`Creating New Gradle Builds
+<https://guides.gradle.org/creating-new-gradle-builds/>`__ guide 
+or the `Building Maven
+<https://maven.apache.org/guides/development/guide-building-maven.html>`__ guide
 for more information on how to set up your project.
 
 .. _add-mongodb-dependency:
 
 Add MongoDB as a Dependency
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-If you are using `Gradle <https://gradle.org/>`__, add the following to your
-``build.gradle.kts`` dependencies list:
+If you are using `Gradle <https://gradle.org/>`__ to manage your
+packages, add the following entry to your ``build.gradle.kts``
+dependencies list:
 
 .. include:: /includes/kotlin-driver-coroutine-gradle-versioned.rst
 
-If you are using `Maven <https://maven.apache.org/>`__, add the following to
-your ``pom.xml`` dependencies list:
+If you are using `Maven <https://maven.apache.org/>`__ to manage your
+packages, add the following entry to your ``pom.xml`` dependencies list:
 
 .. include:: /includes/kotlin-driver-coroutine-maven-versioned.rst
 
-Once you configure your dependencies, ensure they are available to your
-project which may require running your dependency manager and refreshing
-the project in your IDE.
+After you configure your dependencies, ensure that they are available to your
+project by running the dependency manager and refreshing the
+project in your IDE.
+
+Add Serialization Library Dependencies
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+To enable the driver to convert between Kotlin objects and BSON, the
+data format for documents in MongoDB, you must also add one or both of the
+following serialization packages to your application:
+
+- ``bson-kotlinx`` *(Recommended)*
+- ``bson-kotlin``
+
+If you are using Gradle to manage your packages, add one of the following
+entries to your ``build.gradle.kts`` dependencies list: 
+
+.. include:: /includes/serialization-libs-gradle-versioned.rst
+
+If you are using Maven to manage your packages, add one of the following
+entries to your ``pom.xml`` dependencies list:
+
+.. include:: /includes/serialization-libs-maven-versioned.rst
+
+After you configure your dependencies, ensure that they are available to your
+project by running the dependency manager and refreshing the
+project in your IDE.
+
+To learn more about these packages, see
+:ref:`fundamentals-kotlin-serialization`.
 
 Create a MongoDB Cluster
 ------------------------
 
 After setting up your Kotlin project dependencies, create a MongoDB cluster
-where you can store and manage your data. Complete the
-:atlas:`Get Started with Atlas </getting-started?jmp=docs_driver_kotlin>` guide
+in which you can store and manage your data. Complete the
+:atlas:`Get Started with Atlas </getting-started?jmp=docs_driver_kotlin>` tutorial
 to set up a new Atlas account, create and launch a free tier MongoDB cluster,
-load datasets, and interact with the data.
+and load sample datasets.
 
-After completing the steps in the Atlas guide, you should have a new MongoDB
-cluster deployed in Atlas, a new database user, and sample datasets loaded
-into your cluster.
+After you complete the steps in the Get Started with Atlas tutorial, you
+have a new MongoDB cluster deployed in Atlas, a new database user, and
+sample data loaded into your cluster.
 
 Connect to your Cluster
 -----------------------
 
-In this step, we create and run an application that uses the MongoDB Kotlin
-driver to connect to your MongoDB cluster and run a query on the sample data.
+This step shows how to create and run an application that uses the
+{+driver-short+} to connect to your MongoDB cluster and run a query on
+the sample data.
 
-We pass instructions to the driver on how to connect to your
-MongoDB cluster in a string called the *connection string*. This string
-includes information on the hostname or IP address and port of your
-cluster, authentication mechanism, user credentials when applicable, and
-other connection options.
+First, you must specify how the driver connects to your MongoDB cluster
+by including a *connection string* in your code. This string includes
+information on the hostname or IP address and port of your cluster,
+authentication mechanism, user credentials, and other connection
+options.
 
-If you are connecting to an instance or cluster that is not hosted by Atlas,
-see :ref:`Other Ways to Connect to MongoDB <kotlin-other-ways-to-connect>` for
+If you are connecting to an instance or cluster that is not hosted on Atlas,
+see the :ref:`Other Ways to Connect to MongoDB
+<kotlin-other-ways-to-connect>` section of the Connection Guide for
 instructions on how to format your connection string.
 
 To retrieve your connection string for the cluster and user you created in
 the previous step, log into your Atlas account and navigate to the
-:guilabel:`Database` section and click the :guilabel:`Connect` button for the cluster that you
-want to connect to as shown below.
+:guilabel:`Database` page under Deployment and click the
+:guilabel:`Connect` button for your cluster, which is shown in the following
+image:
 
 .. figure:: /includes/figures/atlas_connection_select_cluster.png
    :alt: Atlas Connection GUI cluster selection screen
 
-Proceed to the :guilabel:`Connect Your Application` step and select the Kotlin driver.
-Select "4.10 or later" for the version.
-Click the :guilabel:`Copy` icon to copy the *connection string* to your clipboard as
-shown below.
+Select the :guilabel:`Drivers` option for connection and select
+:guilabel:`Kotlin` from the list of drivers and :guilabel:`4.10 or
+later` from the version dropdown.
+
+Next, click the :guilabel:`Copy` icon, which is highlighted in the
+following image, to copy your *connection string* to
+your clipboard:
 
 .. figure:: /includes/figures/atlas_connection_copy_string_kotlin.png
    :alt: Atlas Connection GUI connection string screen
@@ -129,20 +170,25 @@ for the next step.
 Query Your MongoDB Cluster from Your Application
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Next, create a file ``QuickStartDataClassExample.kt``. Use the following sample
-code to run a query on your sample dataset in MongoDB Atlas, replacing the
-value of the ``uri`` variable with your MongoDB Atlas connection string.
-The example uses a Kotlin data class to model MongoDB data.
+Next, create a file called ``QuickStartDataClassExample.kt`` in your
+project.
 
-Ensure you replace the "<password>" section of the connection string with
-the password you created for your user that has **atlasAdmin** permissions.
+Copy the following sample code into the file and replace the value of
+the ``uri`` variable with your MongoDB Atlas connection string that you
+saved in the preceding step. Replace the ``"<password>"`` placeholder of
+your connection string with the password you set for your user that has
+**atlasAdmin** permissions:
 
 .. literalinclude:: /examples/generated/QuickStartDataClassExample.snippet.quick-start-data-class.kt
    :language: kotlin
    :caption: QuickStartDataClassExample.kt
 
-When you run the ``main`` function, it should output the details
-of the movie from the sample dataset which should look something like this:
+.. note::
+
+   This example uses a Kotlin data class to model MongoDB data.
+
+When you run the ``main`` function, the application prints the details
+of a movie document that matches the query, as shown in the following output:
 
 .. code-block:: none
    :copyable: false
@@ -153,26 +199,28 @@ of the movie from the sample dataset which should look something like this:
       cast=[Michael J. Fox, Christopher Lloyd, Lea Thompson, Crispin Glover]
    )
 
-To learn more about using data classes to store and retrieve data, refer to
-:ref:`Document Data Format: Data Classes <fundamentals-data-classes>`.
+.. tip:: Data Classes
+
+   To learn more about using data classes to store and retrieve data,
+   see the :ref:`fundamentals-data-classes` guide.
 
-If you receive no output or an error, check whether you included the proper
-connection string in your Kotlin class, and whether you loaded the sample dataset
-into your MongoDB Atlas cluster.
+If you don't see any output or receive an error, check whether you
+included the proper connection string in your application. Also, confirm
+that you successfully loaded the sample dataset into your MongoDB Atlas cluster.
 
 .. important:: Known connection issue when using TLS v1.3
 
-   If you encounter an error connecting to your MongoDB instance or cluster
-   that resembles the following while running your application, you may need
-   to update your JDK to the latest patch release:
+   If you encounter the following error while connecting to your MongoDB
+   instance, you must update your JDK to the latest patch release:
 
    .. code-block:: none
       :copyable: false
 
       javax.net.ssl.SSLHandshakeException: extension (5) should not be presented in certificate_request
 
    This exception is a known issue when using the TLS 1.3 protocol with
-   specific versions of JDK, but was fixed for the following releases:
+   specific versions of JDK, but this issue is fixed for the following
+   JDK versions:
 
    - JDK 11.0.7
    - JDK 13.0.3
@@ -181,29 +229,28 @@ into your MongoDB Atlas cluster.
    To resolve this error, update your JDK to one of the preceding patch
    versions or a newer one.
 
-After completing this step, you should have a working application that uses
-the Kotlin driver to connect to your MongoDB cluster, run a query on the
+After completing this step, you have a working application that uses
+the {+driver-short+} to connect to your MongoDB cluster, run a query on the
 sample data, and print out the result.
 
 Working with the Document Class (Alternative)
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-In the previous section, you ran a query on a sample collection to retrieve
-data with a data class. In this section, you can learn to
-use a `Document <{+api+}/apidocs/bson/org/bson/Document.html>`__ class
+The preceding section demonstrates how to run a query on a sample
+collection to retrieve data by using a Kotlin data class. This section
+shows how to use the `Document <{+api+}/apidocs/bson/org/bson/Document.html>`__ class 
 to store and retrieve data from MongoDB.
 
-Next, create a new file to contain your application called ``QuickStartDocumentExample.kt``
-in the base package directory of your project. Use the following sample
-code to run a query on your sample dataset in MongoDB Atlas, replacing the
-value of the ``uri`` variable with your MongoDB Atlas connection string.
+In a new file called ``QuickStartDocumentExample.kt``, paste the following sample
+code to run a query on your sample dataset in MongoDB Atlas. Replace the
+value of the ``uri`` variable with your MongoDB Atlas connection string:
 
 .. literalinclude:: /examples/generated/QuickStartDocumentExample.snippet.quick-start-document.kt
    :caption: QuickStartDocumentExample.kt
    :language: kotlin
 
-When you run the ``main`` function, it should output the details
-of the movie from the sample dataset which will look something like this:
+When you run the ``main`` function, the application prints the details
+of a movie document that matches the query, as shown in the following output:
 
 .. code-block:: json
    :copyable: false
@@ -217,12 +264,13 @@ of the movie from the sample dataset which will look something like this:
      ...
    }
 
-If you receive no output or an error, check whether you included the proper
-connection string in your Kotlin class, and whether you loaded the sample dataset
-into your MongoDB Atlas cluster.
+If you don't see any output or receive an error, check whether you
+included the proper connection string in your application. Also, confirm
+that you successfully loaded the sample dataset into your MongoDB Atlas cluster.
 
 Next Steps
 ----------
 
-Learn how to read and modify data using the Kotlin driver in the :ref:`Fundamentals
-CRUD guide <kotlin-crud-operations>`.
+To learn more about the {+driver-short+}, see the
+:ref:`kotlin-fundamentals-landing` guides, which describe relevant
+concepts in detail and provide code examples for performing different tasks.