Merge pull request #270600 from RoseHJM/ade-overview-updates

ADE - Overview Peer review updates

Author: ttorble

articles/deployment-environments/concept-environments-key-concepts.md

@@ -45,7 +45,7 @@ An environment is a collection of Azure resources on which your application is d
 
 ## Identities
 
-in Azure Deployment Environments, you use [managed identities](../active-directory/managed-identities-azure-resources/overview.md) to provide elevation-of-privilege capabilities. Identities can help you provide self-serve capabilities to your development teams without giving them access to the target subscriptions in which the Azure resources are created. 
+In Azure Deployment Environments, you use [managed identities](../active-directory/managed-identities-azure-resources/overview.md) to provide elevation-of-privilege capabilities. Identities can help you provide self-serve capabilities to your development teams without giving them access to the target subscriptions in which the Azure resources are created. 
 
 The managed identity that's attached to the dev center needs to be granted appropriate access to connect to the catalogs. You should grant Contributor and User Access Administrator access to the target deployment subscriptions that are configured at the project level. The Azure Deployment Environments service uses the specific managed identity to perform the deployment on behalf of the developer.
 
@@ -64,7 +64,7 @@ Project environment types allow you to automatically apply the right set of poli
 
 ## Catalogs
 
-Catalogs help you provide a set of curated IaC templates for your development teams to create environments. Microsoft provides a [*quick start* catalog](https://github.com/microsoft/devcenter-catalog) that contains a set of sample environment defintions. You can attach the quick start catalog to a dev center to make these environment defintions available to all the projects associated with the dev center. You can modify the sample environment definitions to suit your needs. 
+Catalogs help you provide a set of curated IaC templates for your development teams to create environments. Microsoft provides a [*quick start* catalog](https://github.com/microsoft/devcenter-catalog) that contains a set of sample environment definitions. You can attach the quick start catalog to a dev center to make these environment definitions available to all the projects associated with the dev center. You can modify the sample environment definitions to suit your needs. 
 
 Alternately, you can attach your own catalog. You can attach either a [GitHub repository](https://docs.github.com/repositories/creating-and-managing-repositories/about-repositories) or an [Azure DevOps Services repository](/azure/devops/repos/get-started/what-is-repos) as a catalog. 
 
@@ -83,6 +83,14 @@ An environment definition is a combination of an IaC template and an environment
 
 To learn about the structure of an ARM template, the sections of a template, and the properties that are available in those sections, see [Understand the structure and syntax of Azure Resource Manager templates](../azure-resource-manager/templates/syntax.md).
 
+## Built-in roles
+
+Azure Deployment Environments supports three [built-in roles](../role-based-access-control/built-in-roles.md):
+
+- **Dev Center Project Admin**: Creates environments and manages the environment types for a project.
+- **Deployment Environments User**: Creates environments based on appropriate access.
+- **Deployment Environments Reader**: Reads environments that other users created. 
+
 ## Resources shared with Microsoft Dev Box
 
 Azure Deployment Environments and Microsoft Dev Box are complementary services that share certain architectural components. Dev centers and projects are common to both services, and they help organize resources in an enterprise. You can configure projects for Deployment Environments and projects for Dev Box resources in the same dev center. 

articles/deployment-environments/overview-what-is-azure-deployment-environments.md

@@ -1,65 +1,53 @@
 ---
 title: What is Azure Deployment Environments?
 titleSuffix: Azure Deployment Environments
-description: Enable developer teams to spin up infrastructure for deploying apps with project-based templates, while adding governance for Azure resource types, security, and cost.
+description: Enable developer teams to spin up infrastructure for deploying apps with templates, adding governance for Azure resource types, security, and cost.
 ms.service: deployment-environments
 ms.custom: build-2023
 ms.topic: overview
 ms.author: rosemalcolm
 author: RoseHJM
-ms.date: 04/25/2023
+ms.date: 03/28/2024
+
+#customer intent: As a customer, I want to understand to purpose and capabilities of Azure Deployment Environments so that I can determine if the service will benefit my developers.
 ---
 
 # What is Azure Deployment Environments?
 
 Azure Deployment Environments empowers development teams to quickly and easily spin up app infrastructure with project-based templates that establish consistency and best practices while maximizing security. This on-demand access to secure environments accelerates the stages of the software development lifecycle in a compliant and cost-efficient way.
 
-A deployment environment is a preconfigured collection of Azure resources deployed in predefined subscriptions. Azure governance is applied to those subscriptions based on the type of environment, such as sandbox, testing, staging, or production.
+A [*deployment environment*](./concept-environments-key-concepts.md#environments) is a collection of Azure infrastructure resources defined in a template called an [*environment definition*](./concept-environments-key-concepts.md#environment-definitions). Developers can deploy infrastructure defined in the templates in subscriptions where they have access, and build their applications on the infrastructure. For example, you can define a deployment environment that includes a web app, a database, and a storage account. Your web developer can begin coding the web app without worrying about the underlying infrastructure.
 
-:::image type="content" source="./media/overview-what-is-azure-deployment-environments/azure-deployment-environments-scenarios-sml.png" lightbox="./media/overview-what-is-azure-deployment-environments/azure-deployment-environments-scenarios.png" alt-text="Diagram that shows the Azure Deployment Environments scenario flow.":::
+Platform engineers can create and manage environment definitions. To specify which environment definitions are available to developers, platform engineers can associate environment definitions with projects, and assign permissions to developers. They can also apply Azure governance based on the type of environment, such as sandbox, testing, staging, or production.
 
-With Azure Deployment Environments, your platform engineer can enforce enterprise security policies and provide a curated set of predefined infrastructure as code (IaC) templates. 
+The following diagram shows an overview of Azure Deployment Environments capabilities. Platform engineers define infrastructure templates and configure subscriptions, identity, and permissions. Developers create environments based on the templates, and build and deploy applications on the infrastructure. Environments can support different scenarios, like on-demand environments, sandbox environments for testing, and CI/CD pipelines for continuous integration and continuous deployment.
 
->[!NOTE]
-> Azure Deployment Environments currently supports only Azure Resource Manager (ARM) templates.
+:::image type="content" source="./media/overview-what-is-azure-deployment-environments/azure-deployment-environments-scenarios-sml.png" lightbox="./media/overview-what-is-azure-deployment-environments/azure-deployment-environments-scenarios.png" alt-text="Diagram that shows the Azure Deployment Environments scenario flow.":::
+
+Azure Deployment Environments currently supports only Azure Resource Manager (ARM) templates.
 
 You can [learn more about the key concepts for Azure Deployment Environments](./concept-environments-key-concepts.md).
 
 ## Usage scenarios
 
-Azure Deployment Environments enables usage [scenarios](./concept-environments-scenarios.md) for both DevOps teams and developers. Common scenarios include:
-
-- Quickly create on-demand Azure environments by using reusable IaC templates.
-- Create [sandbox environments](concept-environments-scenarios.md#sandbox-environments-for-investigations) to test your code.
-- Preconfigure various types of environments and seamlessly integrate with your continuous integration and continuous delivery (CI/CD) pipeline.
-- Create preconfigured environments for trainings and demos.
-
-### Developer scenarios
-
-Developers have the following self-service experience when working with [environments](./concept-environments-key-concepts.md#environments).
-
-- Deploy a preconfigured environment for any stage of the development cycle.
-- Spin up a sandbox environment to explore Azure.
-- Create platform as a service (PaaS) and infrastructure as a service (IaaS) environments quickly and easily by following a few simple steps.
-- Deploy environments right from where they work.
-
-Developers create and manage environments for Azure Deployment Environments through the [developer portal](./quickstart-create-access-environments.md), with the [Azure CLI](./how-to-create-access-environments.md) or with the [Azure Developer CLI](./how-to-create-environment-with-azure-developer.md).
+Common [scenarios](./concept-environments-scenarios.md) for Azure Deployment Environments include:
 
 ### Platform engineering scenarios
 
-Azure Deployment Environments helps your platform engineer apply the right set of policies and settings on various types of environments, control the resource configuration that developers can create, and track environments across projects. They perform the following tasks:  
+Azure Deployment Environments helps platform engineers apply the right set of policies and settings on various types of environments, control the resource configuration that developers can create, and track environments across projects. They perform the following tasks:  
 
 - Provide a project-based, curated set of reusable IaC templates.
 - Define specific Azure deployment configurations per project and per environment type.
 - Provide a self-service experience without giving control over subscriptions.
 - Track costs and ensure compliance with enterprise governance policies.
 
-Azure Deployment Environments supports three [built-in roles](../role-based-access-control/built-in-roles.md):
+### Developer scenarios
 
-- **Dev Center Project Admin**: Creates environments and manages the environment types for a project.
-- **Deployment Environments User**: Creates environments based on appropriate access.
-- **Deployment Environments Reader**: Reads environments that other users created. 
+Developers can create environments whenever they need them, and develop their applications on the infrastructure. They can use Azure Deployment Environments to do the following tasks:
 
+- Deploy a preconfigured environment for any stage of the development cycle.
+- Spin up a sandbox environment to explore Azure.
+- Create and manage environments through the [developer portal](./quickstart-create-access-environments.md), with the [Azure CLI](./how-to-create-access-environments.md) or with the [Azure Developer CLI](./how-to-create-environment-with-azure-developer.md).
 
 ## Benefits
 
@@ -72,7 +60,7 @@ Capture and share IaC templates in source control within your team or organizati
 Platform engineering teams can curate environment definitions to enforce enterprise security policies and map projects to Azure subscriptions, identities, and permissions by environment types.
 
 - **Project-based configurations**:
-Create and organize environment definitions by the types of applications that development teams are working on, rather than using an unorganized list of templates or a traditional IaC setup.
+Organize environment definitions by the type of application that development teams are working on, rather than using an unorganized list of templates or a traditional IaC setup.
 
 - **Worry-free self-service**:
 Enable your development teams to quickly and easily create app infrastructure (PaaS, serverless, and more) resources by using a set of preconfigured templates. You can also track costs on these resources to stay within your budget.
@@ -86,11 +74,9 @@ Use APIs to provision environments directly from your preferred CI tool, integra
 
 When configuring Deployment Environments, you might see Dev Box resources and components. You might even see informational messages regarding Dev Box features. If you're not configuring any Dev Box features, you can safely ignore these messages.
 
-## Next steps
-Start using Azure Deployment Environments:
+## Related content
 
-- [Key concepts for Azure Deployment Environments](./concept-environments-key-concepts.md)
 - [Azure Deployment Environments scenarios](./concept-environments-scenarios.md)
-- [Quickstart: Create dev center and project (Azure Resource Manager)](./quickstart-create-dev-center-project-azure-resource-manager.md)
 - [Quickstart: Create and configure a dev center](./quickstart-create-and-configure-devcenter.md)
-- [Quickstart: Create and access environments](./quickstart-create-access-environments.md)
+- [Quickstart: Create dev center and project (Azure Resource Manager)](./quickstart-create-dev-center-project-azure-resource-manager.md)
+