Updates from Dhruv's review

Author: RoseHJM

articles/dev-box/concept-what-are-team-customizations.md

@@ -5,7 +5,7 @@ author: RoseHJM
 ms.author: rosemalcolm
 ms.service: dev-box
 ms.topic: concept-article
-ms.date: 10/2/2024
+ms.date: 11/05/2024
 
 #customer intent: As a Project Admin or Dev Center Admin, I want to understand how to use Dev Box Team Customizations so that I can create efficient, ready-to-code configurations for my development teams.
 ---
@@ -24,9 +24,9 @@ When you configure Dev Box Team Customizations for your organization, careful pl
 - **Configure your dev center:**
   - Enable project-level catalogs.
   - Assign permissions for Project Admins.
-- **Decide whether to use a catalog:**
-  - Dev center (quick start catalog)
-    - Simple PowerShell or WinGet statements.
+- **Decide whether to use a catalog with custom reusable components:**
+  - Dev center
+    - PowerShell or WinGet statements.
   - Your own catalog
     - Host in Azure Repos or GitHub.
     - Add tasks.
@@ -47,24 +47,24 @@ Dev Box customizations use a yaml formatted file to specify a list of tasks to a
 You can use secrets from your Azure Key Vault in your customization file to clone private repositories, or with any custom task you author that requires an access token.
 
 ## What are tasks?
-A task performs a specific action, like installing software. You can store a collection of curated tasks in a catalog attached to your dev center, with each task in a separate folder. Each task consists of one or more PowerShell scripts, along with a task.yaml file that provides parameters and defines how the scripts run. 
+Dev Box customization tasks are wrappers for PowerShell scripts, allowing you as a platform team to define reusable components that your teams can use in their customizations. WinGet and PowerShell are available as primitive tasks out of the box
 
 ## Differences Between Team and Individual Customizations
-Individual developers can attach a yaml-based customization file when creating their Dev Box to control the development environment on their Dev Box. While teams of developers can share common yaml files, this approach can be inefficient and error-prone, and against compliance policies. Dev Box Team Customizations provides a workflow for developer team leaders, Project Admins, and dev center administrators to preconfigure customization files on Dev Box pools. This way, a developer creating a dev box doesn't need to find and upload a customization file for themselves.
+Individual developers can attach a yaml-based customization file when creating their Dev Box to control the development environment on their Dev Box. An individual customization file should be used only for personal settings and apps. While teams of developers can share common yaml files, this approach can be inefficient and error-prone, and against compliance policies. Dev Box Team Customizations provides a workflow for developer team leaders, Project Admins, and dev center administrators to preconfigure customization files on Dev Box pools. This way, a developer creating a dev box doesn't need to find and upload a customization file for themselves.
 
 ## Key terms
-**Catalog**
-- Repository for storing tasks
-- Hosted on GitHub or Azure Repos
-- Attached to dev center or project to make tasks accessible to the developer team
-**Tasks**
-- Perform specific actions, like installing software
-- Consist of one or more PowerShell scripts and a task.yaml file
-**Customization file**
-- Yaml-based file defining tasks for dev boxes
-**Image definition**
-- Dev box definition or definition.yaml
-- Specifies OS, compute, storage
+When working with Dev Box Team Customizations, you should be familiar with the following key terms:
+
+- **Catalog**
+    - Can be stored in your code repository, or in a separate repository of customization files.
+    - Hosted on GitHub or Azure Repos.
+    - Attached to dev center or project to make tasks accessible to the developer team.
+- **Tasks**
+    - Perform specific actions, like installing software.
+    - Consist of one or more PowerShell scripts and a task.yaml file.
+- **Customization file**
+    - Yaml-based file defining tasks for dev boxes.
+    - When shared across a team, it's called an *image definition* and specifies OS, compute, and storage.
 
 ## Related content
 - [Quickstart: Create Dev Box Team Customizations](quickstart-team-customizations.md)

articles/dev-box/how-to-configure-customization-imaging.md

@@ -5,15 +5,15 @@ author: RoseHJM
 ms.author: rosemalcolm
 ms.service: dev-box
 ms.topic: how-to
-ms.date: 11/01/2024
+ms.date: 11/05/2024
 
 #customer intent: As a dev center administrator or Project Admin, I want to configure dev box pools to use image definition files so that my development teams can create customized dev boxes.
 ---
 
-# Configure imaging for Dev Box Team Customizations
-Using a customization file simplifies the creation of dev boxes for your team. With Microsoft Dev Box customizations, you can either apply the customization file directly when creating a dev box or use it to create an image. Creating an image optimizes customizations and provides a reusable image for your team, saving time during dev box creation. In this article, you learn how to configure a pool to use a customization file as an image and build a reusable image.
+# Create a shared Customization
+Using a customization file simplifies the creation of dev boxes for your team. With dev box customizations, you can create a shared team customization by creating a customization file called an *image definition*. Creating a reusable image from this image definition optimizes customizations and saves time during dev box creation. In this article, you learn how to configure a pool to use an image definition and build reusable images for your development teams.
 
-Process overview:
+To configure imaging for Dev Box Team Customizations, follow these steps:
 1. Enable project-level catalogs.
 1. Configure catalog sync settings for the project.
 1. Attach a catalog that contains a definition file.
@@ -37,7 +37,7 @@ To manage a dev box pool, you need the following permissions:
 
 | Action | Permissions required |
 |---|---|
-| _Create, delete, or update a dev box pool_ | - Owner or Contributor permissions on an Azure subscription or a specific resource group. </br> - DevCenter Project Admin permissions for the project. |
+| _Create, delete, or update a dev box pool_ | - Owner or Contributor permissions on an Azure subscription or a specific resource group. </br>- DevCenter Project Admin permissions for the project. |
 
 ## Enable project-level catalogs
 
@@ -127,7 +127,7 @@ To build an image from a customization file, follow these steps:
 
    :::image type="content" source="./media/how-to-configure-customization-imaging/customizations-image-build-progress-small.png" alt-text="Screenshot of the Image definition page, with the image status Progressing highlighted." lightbox="./media/how-to-configure-customization-imaging/customizations-image-build-progress.png":::  
 
-When the build completes successfully, the image is available for use in the dev box pool. You can now create dev boxes from the pool, and the customizations are applied to each dev box.
+When the build completes successfully, the dev box pool automatically uses the image for new dev boxes. You don't need to do any extra configuration to assign the image to the pool. You can now create dev boxes from the pool, and the customizations are applied to each dev box.
 
 ## Related content
 - [Microsoft Dev Box Team Customizations](concept-what-are-team-customizations.md)

articles/dev-box/how-to-create-customization-tasks-catalog.md

@@ -5,14 +5,14 @@ author: RoseHJM
 ms.author: rosemalcolm
 ms.service: dev-box
 ms.topic: how-to
-ms.date: 10/26/2024
+ms.date: 11/05/2024
 
 #customer intent: As a dev center administrator or Project Admin, I want to create additional tasks in a catlog so that I can create a specific customization in a customization or image definition file.
 ---
 
 # Create Tasks for Dev Box Team Customizations
 
-Creating tasks for Dev Box Team Customizations allows you to define specific actions for your dev boxes, ensuring a consistent and efficient development environment. Creating new tasks in a catalog allows you to create customizations tailored to your development teams and add guardrails around the configurations that are possible. This article guides you through creating a catalog for customization tasks, adding tasks, and attaching the catalog to a dev center or project.
+Creating tasks for Dev Box Team Customizations allows you to define specific actions for your dev boxes, ensuring a consistent and efficient development environment. Creating new tasks in a catalog allows you to create reusable components tailored to your development teams and add guardrails around the configurations that are possible. This article guides you through creating a catalog for customization tasks, adding tasks, and attaching the catalog to a dev center or project.
 
 [!INCLUDE [customizations-preview-text](includes/customizations-preview-text.md)]
 
@@ -28,6 +28,8 @@ To complete the steps in this article, you must have:
 ## What are tasks?
 A task performs a specific action, like installing software. Each task consists of one or more PowerShell scripts, along with a task.yaml file that provides parameters and defines how the scripts run. You can also include a PowerShell command in the task.yaml file. You can store a collection of curated tasks in a catalog attached to your dev center, with each task in a separate folder. Dev Box supports using a GitHub repository or an Azure Repos repository as a catalog and scans a specified folder of the catalog recursively to find task definitions.
 
+WinGet and PowerShell are available from any dev center without requiring a catalog. If your customizations use only Winget or PowerShell, you can create tasks that use them in a customization file. If you need to use other tools or scripts, you can create tasks in a catalog.
+
 Microsoft provides a quick start catalog to help you get started with customizations. It includes a default set of tasks that define common tasks:
 
 - Install software with WinGet package manager
@@ -38,7 +40,7 @@ Microsoft provides a quick start catalog to help you get started with customizat
 
 ## Create tasks in a catalog
 
-Tasks, such as installing software or running scripts, are organized into a catalog. You create and manage tasks in a catalog, define new tasks, and attach your catalog to a dev center. With Microsoft's quick start catalog, you can get started with common tasks like installing software with WinGet, deploying desired state configurations, cloning repositories, configuring applications, and running PowerShell scripts. 
+Tasks, such as installing software or running scripts, are organized into a catalog. You create and manage tasks in a catalog, define new tasks, and attach your catalog to a dev center. With Microsoft's quick start catalog, you can get started with common tasks like installing software, deploying desired state configurations, cloning repositories, and configuring applications. 
 
 ### Define new tasks
 To create and manage tasks for Dev Box Team Customizations, follow these steps:
@@ -51,19 +53,6 @@ To create and manage tasks for Dev Box Team Customizations, follow these steps:
 
 1. Create a configuration file for those tasks by following the steps in [Write a customization file](./how-to-write-customization-file.md).
 
-### Customize your dev box by using existing WinGet Configuration files
-WinGet Configuration takes a config-as-code approach to defining the unique sets of software and configuration settings needed to get your Windows environment in a ready-to-code state. These configuration files can also be used to set up a Dev Box, by using a WinGet task included in the Microsoft provided quickstart catalog mentioned earlier.
-The following example shows a dev box customization file that calls an existing WinGet DSC file.
-
-```yml
-tasks:
-    - name: winget
-      parameters:
-          configure: "projectConfiguration.dsc.yaml"
-```
-
-To learn more about WinGet Configuration, see [WinGet Configuration](https://aka.ms/winget-configuration).
-
 ### Use secrets from an Azure Key Vault
 You can use secrets from your Azure Key Vault in your yaml configurations to clone private repositories, or with any custom task you author that requires an access token.