fixes

Author: alexwolfmsft

docs/azure/sdk/authentication/best-practices.md

@@ -25,15 +25,15 @@ For information on this approach, see [Authenticate using Microsoft Entra ID](/d
 
 Other types of .NET apps can reuse credential instances as follows:
 
-:::code language="csharp" source="../snippets/auth-best-practices/Program.cs" id="snippet_credential_reuse_noDac" highlight="7, 11" :::
+:::code language="csharp" source="../snippets/auth-best-practices/Program.cs" id="snippet_credential_reuse_noDac" highlight="8, 12" :::
 
 ## Understand the managed identity retry strategy
 
 The Azure Identity library for .NET allows you to authenticate via managed identity with `ManagedIdentityCredential`. The way you use `ManagedIdentityCredential` impacts the applied retry strategy:
 
 - When used via `DefaultAzureCredential`:
   - No retries are attempted when token acquisition fails.
-- When used via any other approach, such as through `ChainedTokenCredential` or `ManagedIdentityCredential` directly:
+- When used via any other approach, such as `ChainedTokenCredential` or `ManagedIdentityCredential` directly:
   - The time interval between retries starts at 0.8 seconds, and a maximum of five retries are attempted.
   - When the Azure service to which you're authenticating provides a `Retry-After` response header, the next retry is delayed by the duration specified in that header's value.
   - When the service doesn't provide a `Retry-After` header, the maximum permissible delay between retries is 1 minute.

docs/azure/sdk/includes/default-azure-credential-usage.md

@@ -1,29 +1,29 @@
 
-`DefaultAzureCredential` is the easiest way to get started with the Azure Identity library, but with that convenience comes certain tradeoffs. Perhaps the most significant tradeoff is the credential chain's indeterministic behavior - that is, the specific credential in the [chain](/dotnet/api/azure.identity.defaultazurecredential?view=azure-dotnet) that will succeed and be used for request authentication can't be guaranteed ahead of time. In a production environment, this unpredictability can introduce significant and sometimes subtle problems. Once you deploy your app to Azure, you should understand the app's authentication requirements.
+`DefaultAzureCredential` is the most approachable way to get started with the Azure Identity library, but that convenience also introduces certain tradeoffs. For example, the specific credential in the [chain](/dotnet/api/azure.identity.defaultazurecredential?view=azure-dotnet) that will succeed and be used for request authentication can't be guaranteed ahead of time. In a production environment, this unpredictability can introduce significant and sometimes subtle problems.
 
 For example, consider the following hypothetical sequence of events:
 
-1. An organization's security team mandates that all apps use managed identity to authenticate to Azure resources.
+1. An organization's security team mandates all apps use managed identity to authenticate to Azure resources.
 1. For months, a .NET app hosted on an Azure Virtual Machine (VM) successfully uses `DefaultAzureCredential` to authenticate via managed identity.
 1. Unbeknownst to the support team, a developer installs the Azure CLI on that VM and runs the `az login` command to sign-in to Azure.
-1. Authentication via the original managed identity unexpectedly begins to fail due to changes in the Azure environment.
-1. `DefaultAzureCredential` skips `ManagedIdentityCredential` and searches for the next available credential, which is the Azure CLI credentials.
+1. Due to a change in the Azure environment, Authentication via the original managed identity unexpectedly begins to fail.
+1. `DefaultAzureCredential` skips the failed `ManagedIdentityCredential` and searches for the next available credential, which is the Azure CLI credentials.
 1. Because logging is disabled by default, nobody is aware of this failure, as `DefaultAzureCredential` recovers gracefully.
 
-`DefaultAzureCredential` can also introduce the following challenges:
+`DefaultAzureCredential` also introduces the following challenges in some scenarios:
 
-- **Debugging challenges**: When authentication fails, it can be challenging to debug and identify the offending credential. You must enable logging to see the progression from one credential to the next and the success/failure status of each. For more information, see [Debug a chained credential](/dotnet/azure/sdk/authentication/credential-chains?tabs=dac#debug-a-chained-credential).
-- **Performance overhead**: The process of sequentially trying multiple credentials can introduce performance overhead. For example, when running on a local development machine, managed identity is unavailable. Consequently, `ManagedIdentityCredential` always fails in the local development environment, unless explicitly disabled via its corresponding `Exclude`-prefixed property.
+- **Debugging challenges**: When authentication fails, it can be difficult to debug and identify the offending credential. You must enable logging to see the progression from one credential to the next and the success or failure status of each. For more information, see [Debug a chained credential](/dotnet/azure/sdk/authentication/credential-chains?tabs=dac#debug-a-chained-credential).
+- **Performance overhead**: Sequentially attempting multiple credentials can introduce performance overhead. For example, when running on a local development machine, managed identity is unavailable. Consequently, `ManagedIdentityCredential` always fails in the local development environment, unless explicitly disabled via its corresponding `Exclude`-prefixed property.
 
-To prevent these types of subtle issues or silent failures in production apps, strongly consider moving from `DefaultAzureCredential` to one of the following solutions:
+To prevent these types of subtle issues or silent failures in production apps, strongly consider moving from `DefaultAzureCredential` to one of the following deterministic solutions:
 
 - A specific `TokenCredential` implementation, such as `ManagedIdentityCredential`. See the [**Derived** list](/dotnet/api/azure.core.tokencredential?view=azure-dotnet&preserve-view=true#definition) for options.
 - A pared-down `ChainedTokenCredential` implementation optimized for the Azure environment in which your app runs. `ChainedTokenCredential` essentially creates a specific allow-list of acceptable credential options, such as `ManagedIdentity` for production and `VisualStudioCredential` for development.
 
-Consider the following `DefaultAzureCredential` example:
+For example, consider the following `DefaultAzureCredential` configuration:
 
-:::code language="csharp" source="../snippets/authentication/credential-chains/Program.cs" id="snippet_Dac" highlight="6":::
+:::code language="csharp" source="../snippets/authentication/credential-chains/Program.cs" id="snippet_Dac" highlight="6,7":::
 
-Replace the preceding code with the following `ChainedTokenCredential` implementation, specifying your desired credentials:
+Replace the preceding code with the following `ChainedTokenCredential` implementation to intentionally specify your desired credentials:
 
-:::code language="csharp" source="../snippets/authentication/credential-chains/Program.cs" id="snippet_Dac" highlight="snippet_Ctc":::
+:::code language="csharp" source="../snippets/authentication/credential-chains/Program.cs" id="snippet_Ctc" highlight="6-8":::