tweaks

Author: alexwolfmsft

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

@@ -15,7 +15,7 @@ This article offers guidelines to help you maximize the performance and reliabil
 
 ## Reuse credential instances
 
-To improve app resilience, reuse credential instances when possible to reduce the number of access token requests issued to Microsoft Entra ID. When a credential is reused, an attempt is made to fetch a token from the app token cache managed by the underlying MSAL dependency. For more information, see [Token caching in the Azure Identity client library](https://github.com/Azure/azure-sdk-for-net/blob/main/sdk/identity/Azure.Identity/samples/TokenCache.md). 
+Reuse credential instances when possible to improve app resilience and reduce the number of access token requests issued to Microsoft Entra ID. When a credential is reused, an attempt is made to fetch a token from the app token cache managed by the underlying MSAL dependency. For more information, see [Token caching in the Azure Identity client library](https://github.com/Azure/azure-sdk-for-net/blob/main/sdk/identity/Azure.Identity/samples/TokenCache.md). 
 
 > [!NOTE]
 > A high-volume app that doesn't reuse credentials may encounter HTTP 429 throttling responses from Microsoft Entra ID, which can lead to app outages.
@@ -35,7 +35,7 @@ Other types of .NET apps can reuse credential instances as follows:
 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.
+  - No retries are attempted when token acquisition fails, which makes this the least resilient option.
 - 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.
   - If 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.

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

@@ -6,14 +6,14 @@ For example, consider the following hypothetical sequence of events:
 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. Without telling the support team, a developer installs the Azure CLI on that VM and runs the `az login` command to sign-in to Azure.
-1. Due to a separate configuration change in the Azure environment, Authentication via the original managed identity unexpectedly begins to fail.
+1. Due to a separate configuration change in the Azure environment, authentication via the original managed identity unexpectedly begins to fail silently.
 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, the team is unaware of this silent authentication failure.
+1. The team is unaware of the hidden authentication failure because logging is disabled by default.
 
 `DefaultAzureCredential` also introduces the following challenges in some scenarios:
 
-- **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, on a local development machine, managed identity is unavailable. Consequently, `ManagedIdentityCredential` always fails locally, unless explicitly disabled via its corresponding `Exclude`-prefixed property.
+- **Debugging challenges**: When authentication fails, it can be difficult to identify and [debug the offending credential](/dotnet/azure/sdk/authentication/credential-chains?tabs=dac#debug-a-chained-credential). Enable logging to see the sequential progression and success or failure status of each credential.
+- **Performance overhead**: Sequential credential attempts can introduce performance overhead. For example, managed identity is unavailable on a local development machine. Consequently, `ManagedIdentityCredential` always fails locally, 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 deterministic solutions: