MDB - customizations concepts updates - it2

Author: RoseHJM

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

@@ -17,14 +17,18 @@ ms.date: 05/09/2025
 [!INCLUDE [note-build-2025](includes/note-build-2025.md)]
 
 
-Starting developers on a new project or team is often complex and time consuming. The Microsoft Dev Box customizations feature helps you streamline the setup of the developer environment. With customizations, you can configure ready-to-code workstations with the necessary applications, tools, repositories, code libraries, packages, and build scripts.
+Getting developers started on a new project or team is often complex and time consuming. The Microsoft Dev Box customizations feature helps you streamline the setup of the developer environment. With customizations, you can configure ready-to-code workstations with the necessary applications, tools, repositories, code libraries, packages, and build scripts.
 
 Dev Box customizations let you:
 - Install the necessary tools and applications.
 - Enforce organizational security policies.
 - Ensure consistency across dev boxes.
 
-Microsoft Dev Box offers two ways to use customizations. Team customizations are used to create a shared configuration for a team of developers. User customizations are used to create a personal configuration for an individual developer. The following table summarizes the differences between the two types of customizations.
+Microsoft Dev Box offers two ways to use customizations. 
+
+- *Team customizations* create a standard shared configuration for a team of developers in place of creating multiple standard or *golden* images for your teams. 
+
+- *User customizations* enable developers to create a configuration for their personal preferences. User customizations enable developers to store their configuration in a file and run it when they create a dev box, providing consistency across all their dev boxes.  
 
 | Feature                     | Team customizations       | User customizations |
 |-----------------------------|---------------------------|---------------------------|
@@ -37,24 +41,25 @@ Microsoft Dev Box offers two ways to use customizations. Team customizations are
 
 ## What is a customization file?
 
-Dev Box customizations use a YAML-formatted file to specify a list of tasks to apply from the dev center or a catalog when developers are creating a dev box. These tasks identify the catalog task and provide parameters like the name of the software to install. Developers create their own customization files or use shared ones. 
-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.
+Dev Box customizations use a YAML-formatted file to specify a list of tasks to apply from the dev center or a catalog when developers are creating a dev box. These tasks identify the catalog task and provide parameters like the name of the software to install. Developers can create their own customization files or use a shared customization file.  
+
+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?
 
-Dev Box customization tasks are wrappers for PowerShell scripts. You use them to define reusable components that your teams can use in their customizations. 
-WinGet and PowerShell tasks are available through the platform, and new ones can be added through a catalog.
-Tasks run in either a system context or a user context after sign-in.
-Team customizations are defined by project admins and can use both custom and built-in tasks.
-User customizations can only use system tasks if the user is an administrator, or if the tasks are custom tasks preapproved by through a catalog.
-When you're creating tasks, determine which of them need to run in a system context and which of them can run in a user context (after sign-in). 
-When creating tasks, determine which need to run in a system context and which run in a user context after sign-in.
+Dev Box customization tasks are wrappers for PowerShell scripts. You use them to define reusable components that your teams can use in their customizations. WinGet and PowerShell tasks are available through the platform, and new ones can be added through a catalog. Tasks can either be run in a system context, or a user context after login. 
+- Team customizations are defined by project admins and can use both custom and built-in tasks. 
+- User customizations can only use system tasks if the user is an administrator, or if the tasks are custom tasks pre-approved by through a catalog. Standard dev box users cannot run the built-in PowerShell and WinGet tasks in a system context, ensuring that there is no escalation of privilege. 
+
+When you're creating tasks, determine which need to run in a system context and which of them can run in a user context (after sign-in).  
 
 ## Differences between team customizations and user customizations
 
-Individual developers can upload a customization file when creating their dev box to control the development environment. Developers should use user customizations only for personal settings and apps. Tasks specified in the user customization file run only in the user context, after sign-in.
-Developers use user customizations only for personal settings and apps.
-Sharing common YAML files among developer teams is inefficient, leads to errors, and violates compliance policies. Dev Box team customizations allow developer team leads and IT admins to preconfigure customization files, eliminating the need for developers to find and upload these files when creating a dev box.
+Dev Box team customizations allow developer team leads and IT admins to preconfigure customization files for dev box pools, eliminating the need for developers to go through manual setup. 
+
+Microsoft recommends using team customizations to secure and standardize dev box deployments across a team. Sharing common YAML files among developer teams can be inefficient and lead to errors, as well as violate compliance policies.   
+
+In addition to team customizations, individual developers can upload a customization file when creating their dev box to control the development environment. Developers should use individual customizations only for personal settings and apps. 
 
 ## How do customizations work?
 Team customization and user customizations are both YAML-based files that specify a list of tasks to apply when creating a dev box. Select the appropriate tab to learn more about how each type of customization works.
@@ -75,32 +80,28 @@ When you configure Dev Box team customizations for your organization, careful pl
 
 To set up your Dev Box service to support team customizations, follow these steps:
 
-1. **Configure your dev center**:
-   1. Enable project-level catalogs.
-   1. Assign permissions for project admins.
-
-1. **Decide whether to use a catalog with custom reusable components**:
-   1. **Built-in**:
-      1. Use PowerShell or WinGet statements.
-   1. **Catalog**:
-      1. Host in Azure Repos or GitHub.
-      1. Add tasks.
-      1. Attach to a dev center.
-
-1. **Create a customization file**:
-   1. Create a YAML file named `imagedefinition.yaml`.
-
-1. **Specify an image in a dev box pool**:
-   1. Create or modify a dev box pool and specify `imagedefinition.yaml` as the image definition.
-
-1. **Choose how you'll use the image definition**:
-   1. Build the image each time you create a dev box.
-   1. Optimize the image for team customizations.
-
-1. **Create a dev box**:
-   1. Use the developer portal to create your dev box from the configured pool.
-
-For more information, see [Write an image definition file for Dev Box team customizations](how-to-write-image-definition-file.md).
+1. **Configure your dev center:**
+   1. Enable project-level catalogs. 
+   1. Assign permissions for project admins. 
+1. **Decide whether to use a catalog with custom reusable components:** 
+   - Built-in (provided by the platform): 
+      1. Use PowerShell or WinGet built-in tasks (starts with ~/). We recommend starting with the built-in tasks. 
+   - Your own catalog: 
+      1. Host in Azure Repos or GitHub. 
+      1. Add tasks. 
+      1. Attach to a dev center. 
+1. **Create a customization file:**
+   1. Create a customization file called imagedefinition.yaml. 
+1. **Specify an image in a dev box pool:**
+   1. Create or modify a dev box pool and specify imagedefinition.yaml as the image definition. 
+1. **Choose how you'll use the image definition:**  
+   - Run the tasks in the image definition at the time of every dev box creation 
+   - Optimize  your image definition into a custom image. 
+1. **Create dev box:**
+    1. Create your dev box from the configured pool by using the developer portal. 
+
+To learn more about team customization and writing image definitions, see  [Write an image definition file for Dev Box team customizations](how-to-write-image-definition-file.md).
+Then, to learn how to optimize your image definition into a custom image, see [Configure imaging for Dev Box team customizations](how-to-configure-customization-imaging.md).
 
 # [User customizations](#tab/user-customizations)
 ### How do user customizations work?
@@ -112,22 +113,21 @@ Individual developers can attach a YAML-based customization file when creating t
 
 To set up your Dev Box service to support user customizations, follow these steps:
 
-1. **Use a PowerShell and WinGet tasks**:
-   1. Platform supports PowerShell and WinGet.
-   1. No catalog required.
-   1. No further configuration required.
-
-1. **Create a customization file**:
-   1. Create a YAML-based customization file.
-
-1. **Create a dev box**:
-   1. Use the developer portal to create your dev box from the configured pool.
-   1. Upload and validate your customization file during the dev box creation process.
-
-1. **Dev box creation**:
-   1. The dev box is created with the specified customizations.
-
-For more information, see [Write a user customization file for a dev box](how-to-write-user-customization-file.md).
+1. **Decide whether to use a catalog with custom reusable components:** 
+    1. Built-in (provided by the platform): 
+        1. Use PowerShell or WinGet built-in tasks (starts with ~/). We recommend starting with the built-in tasks.
+    1. Your own catalog: 
+        1. Host in Azure Repos or GitHub. 
+        1. Add tasks. 
+        1. Attach to a dev center. 
+1. **Create a customization file:**  
+    1. Create a customization file. 
+1. **Create dev box:**  
+    1. Create your dev box from the configured pool by using the developer portal. 
+    1. Upload and validate your customization file as you create your dev box. 
+1. Dev box is created with customizations. 
+
+To learn more about user customizations, see [Write a user customization file for a dev box](how-to-write-user-customization-file.md).
 
 ---