Merge pull request #14727 from LizCasey1/495998-aac-qual-acrolinx

Bulk Edit: AAC quality check Acrolinx clarity fixes - Replace may as n…

Author: v-ccolin

docs/ai-ml/guide/rag/rag-llm-evaluation-phase.md

@@ -22,7 +22,7 @@ This article is part of a series. Read the [introduction](./rag-solution-design-
 
 ## Language model evaluation metrics
 
-There are several metrics that you should use to evaluate the language model's response, including groundedness, completeness, utilization, relevancy, and correctness. Because the overall goal of the RAG pattern is to provide relevant data as context to a language model when generating a response, ideally, each of the above metrics should score highly. However, depending on your workload, you may need to prioritize one over another.
+There are several metrics that you should use to evaluate the language model's response, including groundedness, completeness, utilization, relevancy, and correctness. Because the overall goal of the RAG pattern is to provide relevant data as context to a language model when generating a response, ideally, each of the above metrics should score highly. However, depending on your workload, you might need to prioritize one over another.
 
 > [!IMPORTANT]
 > Language model responses are nondeterministic, which means that the same prompt to a language model often returns different results. This concept is important to understand when you use a language model as part of your evaluation process. Consider using a target range instead of a single target when you evaluate language model use.
@@ -121,7 +121,7 @@ There are several ways to evaluate correctness, including:
 
 When correctness is low, do the following tasks:
 
-1. Ensure that the chunks provided to the language model are factually correct and there's no data bias. You may need to correct any issues in the source documents or content.
+1. Ensure that the chunks provided to the language model are factually correct and there's no data bias. You might need to correct any issues in the source documents or content.
 1. If the chunks are factually correct, evaluate your prompt.
 1. Evaluate if there are inherit inaccuracies in the model that needs to be overcome with additional factual grounding data or fine-tuning.
 
@@ -161,7 +161,7 @@ This metric combination is one where prioritizing one over the other could be ve
 
 ### Utilization and completeness
 
-Utilization and completeness metrics together help evaluate the effectiveness of the retrieval system. High utilization (0.9) with low completeness (0.3) indicates the system retrieves accurate but incomplete information. For instance, when asked about World War II causes, the system might perfectly retrieve information about the invasion of Poland but miss other crucial factors. This scenario may indicate that there are chunks with relevant information that weren't used as part of the context. To address this scenario, consider returning more chunks, evaluating your chunk ranking strategy, and evaluating your prompt.
+Utilization and completeness metrics together help evaluate the effectiveness of the retrieval system. High utilization (0.9) with low completeness (0.3) indicates the system retrieves accurate but incomplete information. For instance, when asked about World War II causes, the system might perfectly retrieve information about the invasion of Poland but miss other crucial factors. This scenario might indicate that there are chunks with relevant information that weren't used as part of the context. To address this scenario, consider returning more chunks, evaluating your chunk ranking strategy, and evaluating your prompt.
 
 ### Groundedness and utilization and similarity
 

docs/antipatterns/busy-database/index.md

@@ -18,10 +18,10 @@ Offloading processing to a database server can cause it to spend a significant p
 
 Many database systems can run code. Examples include stored procedures and triggers. Often, it's more efficient to perform this processing close to the data, rather than transmitting the data to a client application for processing. However, overusing these features can hurt performance, for several reasons:
 
-- The database server may spend too much time processing, rather than accepting new client requests and fetching data.
+- The database server might spend too much time processing, rather than accepting new client requests and fetching data.
 - A database is usually a shared resource, so it can become a bottleneck during periods of high use.
-- Runtime costs may be excessive if the data store is metered. That's particularly true of managed database services. For example, Azure SQL Database charges for [Database Transaction Units (DTUs)][dtu].
-- Databases have finite capacity to scale up, and it's not trivial to scale a database horizontally. Therefore, it may be better to move processing into a compute resource, such as a VM or App Service app, that can easily scale out.
+- Runtime costs might be excessive if the data store is metered. That's particularly true of managed database services. For example, Azure SQL Database charges for [Database Transaction Units (DTUs)][dtu].
+- Databases have finite capacity to scale up, and it's not trivial to scale a database horizontally. Therefore, it might be better to move processing into a compute resource, such as a VM or App Service app, that can easily scale out.
 
 This antipattern typically occurs because:
 
@@ -212,7 +212,7 @@ using (var command = new SqlCommand(...))
 
 - Do not relocate processing if doing so causes the database to transfer far more data over the network. See the [Extraneous Fetching antipattern][ExtraneousFetching].
 
-- If you move processing to an application tier, that tier may need to scale out to handle the additional work.
+- If you move processing to an application tier, that tier might need to scale out to handle the additional work.
 
 ## How to detect the problem
 

docs/antipatterns/busy-front-end/index.md

@@ -121,7 +121,7 @@ public async Task RunAsync(CancellationToken cancellationToken)
 - This approach adds some additional complexity to the application. You must handle queuing and dequeuing safely to avoid losing requests in the event of a failure.
 - The application takes a dependency on an additional service for the message queue.
 - The processing environment must be sufficiently scalable to handle the expected workload and meet the required throughput targets.
-- While this approach should improve overall responsiveness, the tasks that are moved to the back end may take longer to complete.
+- While this approach should improve overall responsiveness, the tasks that are moved to the back end might take longer to complete.
 - Consider combining this with the [Throttling pattern](/azure/architecture/patterns/throttling) to avoid overwhelming backend systems. Prioritize certain clients. For example, if the application has free and paid tiers, throttle customers on the free tier, but not paid customers. See [Priority queue pattern](/azure/architecture/patterns/priority-queue).
 
 ## How to detect the problem

docs/antipatterns/chatty-io/index.md

@@ -217,7 +217,7 @@ await SaveCustomerListToFileAsync(customers);
 
 - When writing data, avoid locking resources for longer than necessary, to reduce the chances of contention during a lengthy operation. If a write operation spans multiple data stores, files, or services, then adopt an eventually consistent approach. See [Data Consistency guidance][data-consistency-guidance].
 
-- If you buffer data in memory before writing it, the data is vulnerable if the process crashes. If the data rate typically has bursts or is relatively sparse, it may be safer to buffer the data in an external durable queue such as [Event Hubs](https://azure.microsoft.com/services/event-hubs).
+- If you buffer data in memory before writing it, the data is vulnerable if the process crashes. If the data rate typically has bursts or is relatively sparse, it might be safer to buffer the data in an external durable queue such as [Event Hubs](https://azure.microsoft.com/services/event-hubs).
 
 - Consider caching data that you retrieve from a service or a database. This can help to reduce the volume of I/O by avoiding repeated requests for the same data. For more information, see [Caching best practices][caching-guidance].
 

docs/antipatterns/extraneous-fetching/index.md

@@ -23,7 +23,7 @@ Antipatterns are common design flaws that can break your software or application
 
 ## Examples of extraneous fetching antipattern
 
-This antipattern can occur if the application tries to minimize I/O requests by retrieving all of the data that it *might* need. This is often a result of overcompensating for the [Chatty I/O][chatty-io] antipattern. For example, an application might fetch the details for every product in a database. But the user may need just a subset of the details (some may not be relevant to customers), and probably doesn't need to see *all* of the products at once. Even if the user is browsing the entire catalog, it would make sense to paginate the results—showing 20 at a time, for example.
+This antipattern can occur if the application tries to minimize I/O requests by retrieving all of the data that it *might* need. This is often a result of overcompensating for the [Chatty I/O][chatty-io] antipattern. For example, an application might fetch the details for every product in a database. But the user might need just a subset of the details (some might not be relevant to customers), and probably doesn't need to see *all* of the products at once. Even if the user is browsing the entire catalog, it would make sense to paginate the results—showing 20 at a time, for example.
 
 Another source of this problem is following poor programming or design practices. For example, the following code uses Entity Framework to fetch the complete details for every product. Then it filters the results to return only a subset of the fields, discarding the rest.
 
@@ -75,7 +75,7 @@ The call to `AsEnumerable` is a hint that there is a problem. This method conver
 
 ## How to fix extraneous fetching antipattern
 
-Avoid fetching large volumes of data that may quickly become outdated or might be discarded, and only fetch the data needed for the operation being performed.
+Avoid fetching large volumes of data that might quickly become outdated or might be discarded, and only fetch the data needed for the operation being performed.
 
 Instead of getting every column from a table and then filtering them, select the columns that you need from the database.
 
@@ -107,7 +107,7 @@ public async Task<IHttpActionResult> AggregateOnDatabaseAsync()
 }
 ```
 
-When using Entity Framework, ensure that LINQ queries are resolved using the `IQueryable` interface and not `IEnumerable`. You may need to adjust the query to use only functions that can be mapped to the data source. The earlier example can be refactored to remove the `AddDays` method from the query, allowing filtering to be done by the database.
+When using Entity Framework, ensure that LINQ queries are resolved using the `IQueryable` interface and not `IEnumerable`. You might need to adjust the query to use only functions that can be mapped to the data source. The earlier example can be refactored to remove the `AddDays` method from the query, allowing filtering to be done by the database.
 
 ```csharp
 DateTime dateSince = DateTime.Now.AddDays(-7); // AddDays has been factored out.
@@ -120,7 +120,7 @@ List<Product> products = query.ToList();
 
 ## Considerations
 
-- In some cases, you can improve performance by partitioning data horizontally. If different operations access different attributes of the data, horizontal partitioning may reduce contention. Often, most operations are run against a small subset of the data, so spreading this load may improve performance. See [Data partitioning][data-partitioning].
+- In some cases, you can improve performance by partitioning data horizontally. If different operations access different attributes of the data, horizontal partitioning might reduce contention. Often, most operations are run against a small subset of the data, so spreading this load might improve performance. See [Data partitioning][data-partitioning].
 
 - For operations that have to support unbounded queries, implement pagination and only fetch a limited number of entities at a time. For example, if a customer is browsing a product catalog, you can show one page of results at a time.
 
@@ -130,7 +130,7 @@ List<Product> products = query.ToList();
 
 - If you see that requests are retrieving a large number of fields, examine the source code to determine whether all of these fields are necessary. Sometimes these requests are the result of poorly designed `SELECT *` query.
 
-- Similarly, requests that retrieve a large number of entities may be sign that the application is not filtering data correctly. Verify that all of these entities are needed. Use database-side filtering if possible, for example, by using `WHERE` clauses in SQL.
+- Similarly, requests that retrieve a large number of entities might be sign that the application is not filtering data correctly. Verify that all of these entities are needed. Use database-side filtering if possible, for example, by using `WHERE` clauses in SQL.
 
 - Offloading processing to the database is not always the best option. Only use this strategy when the database is designed or optimized to do so. Most database systems are highly optimized for certain functions, but are not designed to act as general-purpose application engines. For more information, see the [Busy Database antipattern][BusyDatabase].
 
@@ -191,7 +191,7 @@ For each data source, instrument the system to capture the following:
 
 Compare this information against the volume of data being returned by the application to the client. Track the ratio of the volume of data returned by the data store against the volume of data returned to the client. If there is any large disparity, investigate to determine whether the application is fetching data that it doesn't need.
 
-You may be able to capture this data by observing the live system and tracing the lifecycle of each user request, or you can model a series of synthetic workloads and run them against a test system.
+You might be able to capture this data by observing the live system and tracing the lifecycle of each user request, or you can model a series of synthetic workloads and run them against a test system.
 
 The following graphs show telemetry captured using [New Relic APM][new-relic] during a load test of the `GetAllFieldsAsync` method. Note the difference between the volumes of data received from the database and the corresponding HTTP responses.
 

docs/antipatterns/improper-instantiation/index.md

@@ -16,7 +16,7 @@ keywords:
 
 # Improper Instantiation antipattern
 
-Sometimes new instances of a class are continually created, when it is meant to be created once and then shared. This behavior can hurt performance, and is called an *improper instantiation antipattern*. An antipattern is a common response to a recurring problem that is usually ineffective and may even be counter-productive.
+Sometimes new instances of a class are continually created, when it is meant to be created once and then shared. This behavior can hurt performance and is called an *improper instantiation antipattern*. An antipattern is a common response to a recurring problem that is usually ineffective and might be counter-productive.
 
 ## Problem description
 
@@ -45,7 +45,7 @@ public class NewHttpClientInstancePerRequestController : ApiController
 }
 ```
 
-In a web application, this technique is not scalable. A new `HttpClient` object is created for each user request. Under heavy load, the web server may exhaust the number of available sockets, resulting in `SocketException` errors.
+In a web application, this technique is not scalable. A new `HttpClient` object is created for each user request. Under heavy load, the web server might exhaust the number of available sockets, resulting in `SocketException` errors.
 
 This problem is not restricted to the `HttpClient` class. Other classes that wrap resources or are expensive to create might cause similar issues. The following example creates an instance of the `ExpensiveToCreateService` class. Here the issue is not necessarily socket exhaustion, but simply how long it takes to create each instance. Continually creating and destroying instances of this class might adversely affect the scalability of the system.
 
@@ -106,7 +106,7 @@ public class SingleHttpClientInstanceController : ApiController
 
 - Be careful about setting properties on shared objects, as this can lead to race conditions. For example, setting `DefaultRequestHeaders` on the `HttpClient` class before each request can create a race condition. Set such properties once (for example, during startup), and create separate instances if you need to configure different settings.
 
-- Some resource types are scarce and should not be held onto. Database connections are an example. Holding an open database connection that is not required may prevent other concurrent users from gaining access to the database.
+- Some resource types are scarce and should not be held onto. Database connections are an example. Holding an open database connection that is not required might prevent other concurrent users from gaining access to the database.
 
 - In the .NET Framework, many objects that establish connections to external resources are created by using static factory methods of other classes that manage these connections. These objects are intended to be saved and reused, rather than disposed and re-created. For example, in Azure Service Bus, the `QueueClient` object is created through a `MessagingFactory` object. Internally, the `MessagingFactory` manages connections. For more information, see [Best Practices for performance improvements using Service Bus Messaging][service-bus-messaging].