Adds changes from Ian Ward's review (#41)

Author: sarahsimpers

source/automation.txt

@@ -17,25 +17,29 @@ Automation
 .. contents:: On this page
    :local:
    :backlinks: none
-   :depth: 1
+   :depth: 2
    :class: onecol
 
 |service-fullname| provides an easy way to host and manage your data in
 the cloud. It includes tools that automate the deployment, scaling, and
 maintenance of your {+service+} {+clusters+} to streamline operations,
 reduce manual interventions, and ensure consistent, policy-compliant
 deployments. These tools offer you the flexibility to work with
-|service| through direct scripting, a Kubernetes-native workflow, or
-using Infrastructure as Code (IaC) resources.    
+|service| through direct scripting (such as scripts that call the
+{+atlas-admin-api+}), a Kubernetes-native workflow, or
+using Infrastructure as Code (IaC) tools like Terraform.    
 
-{+service+} Features for Automation
------------------------------------
+{+service+} Features and Recommendations for Automation
+-------------------------------------------------------
+
+Features
+~~~~~~~~
 
 You can automate the management, provisioning, and configuration of
 |service| building blocks like database users and roles, |service|
 {+clusters+}, projects and organizations. Additionally, you can automate 
 setting up and managing of additional {+clusters+} resources, including
-enabling auto-scaling and disk scaling, creating and updating
+enabling auto-scaling compute and storage, creating and updating
 multi-cloud {+clusters+}, monitoring {+cluster+} performance and health,
 automating backups and restores, defining backup policies, and many more.   
 
@@ -46,17 +50,18 @@ deploy and manage |service| at scale with repeatable, accurate, and
 scalable processes. 
 
 {+atlas-admin-api+} 
-~~~~~~~~~~~~~~~~~~~~~~~~
+`````````````````````````````
 
 The {+atlas-admin-api+} provides a |rest|\ful interface that allows you
 to leverage your preferred client such as cURL or Postman to
 directly interact with |api| endpoints that correspond to |service|
-resources.   
+resources. They can also be directly called in your favorite
+programming language or bash script.
 
 To learn more, see :ref:`atlas-admin-api-access`.
 
 GoSDK Client 
-~~~~~~~~~~~~
+````````````
 
 The {+service+} Go SDK client simplifies interaction with the
 {+atlas-admin-api+} by providing pre-built functions and full |api|
@@ -66,65 +71,92 @@ applications quickly and easily.
 
 To learn more, see :ref:`Atlas Go SDK <atlas-admin-sdk>`.
 
+.. _arch-center-iac:
+
 Infrastructure as Code (IaC) Integrations 
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+`````````````````````````````````````````
 
 The integrations with the following :abbr:`IaC (Infrastructure as Code)`
 tools automate the deployment of |service| resources.
 
 HashiCorp Terraform MongoDB Atlas Provider
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+##########################################
 
 Provisions |service| resources across cloud providers (|aws|, |azure|,
 |gcp|) in the workflow of your choice. It allows you to integrate
 |service| into your continuous delivery workflows with the official
-plugin that is verified and tested by HashiCorp. 
+plugin.
 
 Alternatively, you can use the :abbr:`CDKTF (Cloud Development Kit for
 Terraform)` to deploy |service| in preferred languages such as
 JavaScript, TypeScript, Python, Java, C#, and Go. 
 
-To learn more, see :ref:`getting-started-terraform` and
-|service-terraform|. You can also use the Terraform examples in the
+To learn more, see :ref:`getting-started-terraform` and the
+`MongoDB Atlas Provider Terraform docs <https://registry.terraform.io/providers/mongodb/mongodbatlas/latest/docs>`__. You can also use the Terraform examples in the
 {+atlas-arch-center+} such as the :ref:`Org, Project, and
 Cluster<arch-center-hierarchy>` examples to get started. 
 
 CloudFormation Resources
-~~~~~~~~~~~~~~~~~~~~~~~~
+########################
 
 Resources to manage |service| include:
 
 - :github:`JSON and YAML templates
-  <mongodb/mongodbatlas-cloudformation-resources>` allow you to leverage
+  <mongodb/mongodbatlas-cloudformation-resources/tree/master/examples>` allow you to leverage
   multiple different types of |service| resources in the |aws|
   CloudFormation Public Registry.   
-- `AWS Partner Solutions <https://aws.amazon.com/solutions/>`__ enable
-  you to set up an |service| environment in |aws| by using a pre-defined
-  CloudFormation template that creates an |service| project with a
-  standard, single-region, ``M10`` {+cluster+}. 
-- `AWS Cloud Development Kit (CDK) <https://constructs.dev/search?q=&keywords=MongoDB&offset=0>`__
+- `AWS Cloud Development Kit (CDK) <https://constructs.dev/search?q=&keywords=MongoDB&offset=0&tags=mongodb-published>`__
   defines infrastructure using familiar programming languages such as
   JavaScript, TypeScript, Python, Java, C#, and Go. 
 
 To learn more, see `Deploy MongoDB Atlas with AWS CloudFormation <https://www.mongodb.com/developer/products/atlas/deploy-mongodb-atlas-aws-cloudformation/>`__.
 
 {+atlas-cli+} 
-~~~~~~~~~~~~~
+`````````````
 
 Enables you to create, manage, and automate tasks related to |service|
 resources from a unified command line tool. 
 
-To learn more, see :ref:`atlas-cli-ephemeral-cluster` and :ref:`Quick
-Start <atlas-cli-quick-start>`. You can also use the {+atlas-cli+}
+To learn more, see the following resources:
+
+- :ref:`Atlas CLI <atlascli>`
+- :ref:`Quick Start <atlas-cli-quick-start>`
+- :ref:`atlas-cli-ephemeral-cluster`
+
+You can also use the {+atlas-cli+}
 examples in the {+atlas-arch-center+} such as the :ref:`Org, Project,
 and Cluster<arch-center-hierarchy>` examples to get started.
 
 |ak8so| 
-~~~~~~~~~~~~~~~~~~~~~~~~~~~
+`````````````````````````
 
 Allows you to deploy and manage |service| resources using you existing
 Kubernetes tools. The Operator enables management of |service| through
 custom resources applied into Kubernetes, which the Operator uses to
 configure |service|.  
 
 To learn more, see :ref:`ak8so-quick-start-ref`. 
+
+Recommendations
+~~~~~~~~~~~~~~~
+
+If you already have an existing tool integrated into your deployment
+workflow that you use today, we recommend that you use that tool for
+automation. For example, if your developers and operations team are
+used to building custom resource definitions for Kubernetes for
+deployment, use the |ak8so| and Kubernetes for automation in 
+{+service+}.
+
+If you don't already have an existing tool integrated into your development workflow, we recommend an :ref:`IaC tool <arch-center-iac>`
+because they provide more robust options for infrastructure provisioning and state management.
+If you instead call the {+atlas-admin-api+} directly or use the GoSDK, which wraps the {+atlas-admin-api+}, you might need to recreate your
+infrastructure provisioning each time to match your needs across
+environments.
+
+You can also use a combination of multiple tools. For example, use IaC
+tool for provisioning and state management, and leverage the {+atlas-admin-api+}, GoSDK, and {+atlas-cli+} for quick administrative
+tasks that are ephemeral in nature. The {+atlas-cli+} is great for
+local development as well as integration into a suite of tests as part
+of your CI/CD pipeline for application development because it improves
+response times and reduces costs.
+