Merge pull request #215128 from ShawnJackson/about-azure-deployment-environments

edit pass: "About Azure Deployment Environments" articles

Author: itechedit

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

@@ -11,51 +11,65 @@ ms.date: 10/12/2022
 
 # Key concepts for new Azure Deployment Environments Preview users
 
-Learn about the key concepts and components of Azure Deployment Environments Preview. This knowledge can help you to more effectively deploy environments for your scenarios.
+Learn about the key concepts and components of Azure Deployment Environments Preview. This knowledge can help you more effectively deploy environments for your scenarios.
 
 > [!IMPORTANT]
 > Azure Deployment Environments is currently in preview. For legal terms that apply to Azure features that are in beta, in preview, or otherwise not yet released into general availability, see the [Supplemental Terms of Use for Microsoft Azure Previews](https://azure.microsoft.com/support/legal/preview-supplemental-terms/).
 
 ## Dev centers
 
-A dev center is a collection of projects that require similar settings. Dev centers enable dev infrastructure managers to manage the infrastructure-as-code templates made available to the projects using Catalogs, and configure the different types of environments, various development teams can create, using Environment Types.
+A dev center is a collection of projects that require similar settings. Dev centers enable development infrastructure (dev infra) managers to:
+
+- Use catalogs to manage infrastructure as code (IaC) templates that are available to the projects.
+- Use environment types to configure the types of environments that development teams can create.
 
 ## Projects
 
-A project is the point of access for the development team members. When you associate a project with a dev center, all the settings at the dev center level will be automatically applied to the project. Each project can be associated with only one dev center. Dev infra admins can configure different types of environments made available for the project by specifying the environment types appropriate for the specific development team.
+A project is the point of access for the development team. When you associate a project with a dev center, all the settings for the dev center are automatically applied to the project. 
+
+Each project can be associated with only one dev center. Dev infra admins can configure environments for a project by specifying which environment types are appropriate for the development team.
 
 ## Environments
 
-Environment is a collection of Azure resources on which your application is deployed. For example, to deploy a web application, you might create an environment consisting of an [App Service](../app-service/overview.md), [Key Vault](../key-vault/general/basic-concepts.md), [Cosmos DB](../cosmos-db/introduction.md) and a [Storage account](../storage/common/storage-account-overview.md). An environment could consist of both Azure PaaS and IaaS resources such as AKS Cluster, App Service, VMs, databases, etc.
+An environment is a collection of Azure resources on which your application is deployed. For example, to deploy a web application, you might create an environment that consists of [Azure App Service](../app-service/overview.md), [Azure Key Vault](../key-vault/general/basic-concepts.md), [Azure Cosmos DB](../cosmos-db/introduction.md), and a [storage account](../storage/common/storage-account-overview.md). An environment could consist of both Azure platform as a service (PaaS) and infrastructure as a service (IaaS) resources such as an Azure Kubernetes Service (AKS) cluster, virtual machines, and databases.
 
 ## Identities
 
-[Managed Identities](../active-directory/managed-identities-azure-resources/overview.md) are used in Azure Deployment Environments to provide elevation-of-privilege capabilities. Identities will help provide self-serve capabilities to your development teams without them needing any access to the target subscriptions in which the Azure resources are created. The managed identity attached to the dev center needs to be granted appropriate access to connect to the Catalogs and should be granted 'Owner' access to the target deployment subscriptions configured at the project level. Azure Deployment Environments service will use the specific deployment identity to perform the deployment on behalf of the developer.
+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 owner access to the target deployment subscriptions that are configured at the project level. The Azure Deployment Environments service will use the specific managed identity to perform the deployment on behalf of the developer.
 
 ## Dev center environment types
 
-You can use environment types to define the type of environments the development teams can create, for example, dev, test, sandbox, pre-production, or production. Azure Deployment Environments provides the flexibility to name the environment types as per the nomenclature used in your enterprise. When you create an environment type, you'll be able to configure and apply different settings for different environment types based on specific needs of the development teams.
+You can define the types of environments that development teams can create: for example, dev, test, sandbox, pre-production, or production. Azure Deployment Environments provides the flexibility to name the environment types according to the nomenclature that your enterprise uses. You can configure settings for various environment types based on the specific needs of the development teams.
 
 ## Project environment types 
 
-Project Environment Types are a subset of the environment types configured per dev center and help you pre-configure the different types of environments specific development teams can create. You'll be able to configure the target subscription in which Azure resources are created per project per environment type. Project environment types will allow you to automatically apply the right set of policies on different environments and help abstract the Azure governance related concepts from your development teams. The service also provides the flexibility to pre-configure the [managed identity](concept-environments-key-concepts.md#identities) that will be used to perform the deployment and the access levels the development teams will get after a specific environment is created.
+Project environment types are a subset of the environment types that you configure for the dev center. They help you preconfigure the types of environments that specific development teams can create. You can configure the target subscription in which Azure resources are created per project and per environment type. 
+
+Project environment types allow you to automatically apply the right set of policies on environments and help abstract the Azure governance-related concepts from your development teams. The service also provides the flexibility to preconfigure:
+
+- The [managed identity](concept-environments-key-concepts.md#identities) that will be used to perform the deployment.
+- The access levels that the development teams will get after a specific environment is created.
 
 ## Catalogs
 
-Catalogs help you provide a set of curated infra-as-code templates for your development teams to create Environments. 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. Deployment Environments will scan through the specified folder of the repository to find [Catalog Items](#catalog-items), and make them available for use by all the Projects associated with the dev center.
+Catalogs help you provide a set of curated IaC templates for your development teams to create environments. 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. 
+
+Deployment environments scan the specified folder of the repository to find [catalog items](#catalog-items). The environments then make those catalog items available to all the projects associated with the dev center.
 
-## Catalog Items
+## Catalog items
 
-A Catalog Item is a combination of an infra-as-code template and a manifest file. The environment definition will be defined in the template and the manifest will be used to provide metadata about the template. The Catalog Items that you provide in the Catalog will be used by your development teams to create environments in Azure.
+A catalog item is a combination of an IaC template and a manifest file. The template defines the environment, and the manifest provides metadata about the template. Your development teams will use the items that you provide in the catalog to create environments in Azure.
 
 > [!NOTE]
-> During public preview, Azure Deployments Environments uses Azure Resource Manager (ARM) templates.
+> During public preview, Azure Deployment Environments uses Azure Resource Manager (ARM) templates.
 
-## Azure Resource Manager (ARM) templates
+## ARM templates
 
-[Azure Resource Manager (ARM) templates](../azure-resource-manager/templates/overview.md) help you implement the infrastructure as code for your Azure solutions by defining the infrastructure and configuration for your project, the resources to deploy, and the properties of those resources.
+[ARM templates](../azure-resource-manager/templates/overview.md) help you implement the IaC for your Azure solutions by defining the infrastructure and configuration for your project, the resources to deploy, and the properties of those resources.
 
-[Understand the structure and syntax of Azure Resource Manager templates](../azure-resource-manager/templates/syntax.md) describes the structure of an Azure Resource Manager template, the different sections of a template, and the properties that are available in those sections.
+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).
 
 ## Next steps
 

articles/deployment-environments/concept-environments-scenarios.md

@@ -10,65 +10,61 @@ ms.date: 10/12/2022
 ---
 # Scenarios for using Azure Deployment Environments Preview
 
-This article discusses a few possible scenarios and benefits of Azure Deployment Environments Preview, and the resources used to implement those scenarios. Depending on the needs of an enterprise, Azure Deployment Environments can be configured to meet different requirements. 
-
-Some possible scenarios are:
-- Environments as part of a CI/CD pipeline
-- Sandbox environments for investigations
-- On-demand test environments
-- Training sessions, hands-on labs, and hackathons
+This article discusses a few possible scenarios for Azure Deployment Environments Preview, along with the resources that an organization can use to implement those scenarios. Azure Deployment Environments can be configured to meet the needs of an enterprise. 
 
 > [!IMPORTANT]
 > Azure Deployment Environments is currently in preview. For legal terms that apply to Azure features that are in beta, in preview, or otherwise not yet released into general availability, see the [Supplemental Terms of Use for Microsoft Azure Previews](https://azure.microsoft.com/support/legal/preview-supplemental-terms/).
 
 ## Environments as part of a CI/CD pipeline
 
-Creating and managing environments across an enterprise can require significant effort. With Azure Deployment Environments, different types of product lifecycle environments such as development, testing, staging, pre-Production, Production, etc. can be easily created, updated, and plugged into a CI/CD pipeline.
+Creating and managing environments across an enterprise can require significant effort. With Azure Deployment Environments, different types of product lifecycle environments (such as development, testing, staging, pre-production, and production) can be easily created, updated, and plugged into a continuous integration and continuous delivery (CI/CD) pipeline.
 
 In this scenario, Azure Deployment Environments provides the following benefits:
 
-- Organizations can attach a [Catalog](./concept-environments-key-concepts.md#catalogs) and provide common 'infra-as-code' templates to create environments ensuring consistency across teams.
-- Developers and testers can test the latest version of their application by quickly provisioning environments by using reusable templates.
+- Organizations can attach a [catalog](./concept-environments-key-concepts.md#catalogs) and provide common infrastructure as code (IaC) templates to create environments, to help ensure consistency across teams.
+- Developers and testers can test the latest version of their application by using reusable templates to quickly provision environments.
 - Development teams can connect their environments to CI/CD pipelines to enable DevOps scenarios.
-- Central Dev IT teams can centrally track costs, security alerts, and manage environments across different projects and dev centers.
+- Central dev IT teams can centrally track costs, track security alerts, and manage environments across projects and dev centers.
 
 ## Sandbox environments for investigations
 
-Developers often investigate different technologies or infrastructure designs. By default, all environments created with Azure Deployment Environments are created in their own resource group and the Project members get contributor access to those resources by default. 
+Developers often investigate different technologies or infrastructure designs. By default, all environments created with Azure Deployment Environments are in their own resource group. Project members get contributor access to those resources by default. 
 
 In this scenario, Azure Deployment Environments provides the following benefits:
- - Allows developers to add and/or change Azure resources as they need for their development or test environments.
- - Central Dev IT teams can easily and quickly track costs for all the environments used for investigation purposes.
+- Developers can add and change Azure resources as they need for their development or test environments.
+- Central dev IT teams can easily track costs for all the environments that are used for investigations.
 
 ## On-demand test environments
 
-Often developers need to create adhoc test environments that mimic their formal development or testing environments to test a new capability before checking in the code and executing a pipeline. With Azure Deployment Environments, test environments can be easily created, updated, or duplicated. 
+Developers often need to create ad hoc environments that mimic their formal development or test environments, to test a new capability before checking in the code and executing a pipeline. With Azure Deployment Environments, developers can easily create, update, or duplicate test environments. 
 
 In this scenario, Azure Deployment Environments provides the following benefits:
-- Allows teams to access a fully configured environment when it’s needed. 
-- Developers can test the latest version of their application by quickly creating new adhoc environments using reusable templates.
+- Teams can access a fully configured environment when it's needed. 
+- Developers can test the latest version of an application by using reusable templates to quickly create new ad hoc environments.
 
 ## Trainings, hands-on labs, and hackathons
 
-A Project in Azure Deployment Environments acts as a great container for transient activities like workshops, hands-on labs, trainings, or hackathons. The service allows you to create a Project where you can provide custom templates to each user.
+A project in Azure Deployment Environments acts as a container for transient activities like workshops, hands-on labs, trainings, or hackathons. You can create a project to provide custom templates to each user.
 
 In this scenario, Azure Deployment Environments provides the following benefits: 
-- Each trainee can create identical and isolated environments for training. 
-- Easily delete a Project and all related resources when the training is over.
+- Each user can create identical and isolated environments for training. 
+- You can easily delete a project and all related resources when the training is over.
+
+## Deployment options
 
-## Proof of concept deployment vs. scaled deployment
+After you decide to explore Azure Deployment Environments, there are two general paths forward: proof-of-concept deployment or scaled deployment.
 
-Once you decide to explore Azure Deployment Environments, there are two general paths forward: Proof of concept vs scaled deployment.
+### Proof-of-concept deployment
 
-### Proof of concept deployment
+A proof-of-concept deployment is a concentrated effort from a single team to establish organizational value. Although it can be tempting to start with a scaled deployment, that approach tends to fail more often than the proof-of-concept option. 
 
-A **proof of concept** deployment focuses on a concentrated effort from a single team to establish organizational value. While it can be tempting to think of a scaled deployment, the approach tends to fail more often than the proof of concept option. Therefore, we recommend that you start small, learn from the first team, repeat the same approach with two to three additional teams, and then plan for a scaled deployment based on the knowledge gained. For a successful proof of concept, we recommend that you pick one or two teams, and identify their scenarios ([environments as part of a CI/CD pipeline](#environments-as-part-of-a-cicd-pipeline) vs [sandbox environments](#sandbox-environments-for-investigations)), document their current use cases, and then deploy Azure Deployment Environments.
+We recommend that you start small, learn from the first team, repeat the same approach with two to three additional teams, and then plan for a scaled deployment based on the knowledge gained. For a successful proof of concept, we recommend that you pick one or two teams, identify their scenarios ([environments as part of a CI/CD pipeline](#environments-as-part-of-a-cicd-pipeline) versus [sandbox environments](#sandbox-environments-for-investigations)), document their current use cases, and then deploy Azure Deployment Environments.
 
 ### Scaled deployment
 
-A **scaled deployment** consists of weeks of reviewing and planning with an intent of deploying Azure Deployment Environments to the entire enterprise that has hundreds or thousands of developers.
+A scaled deployment consists of weeks of reviewing and planning with an intent of deploying Azure Deployment Environments to the entire enterprise, which has hundreds or thousands of developers.
 
 ## Next steps
 
-- To get started with the service, [Quickstart: Create and configure the Azure Deployment Environments dev center](./quickstart-create-and-configure-devcenter.md)
-- Learn more about [Azure Deployment Environments key concepts](./concept-environments-key-concepts.md)
+- To get started with the service, see [Quickstart: Create and configure the Azure Deployment Environments dev center](./quickstart-create-and-configure-devcenter.md).
+- Learn more about [Azure Deployment Environments key concepts](./concept-environments-key-concepts.md).