address acrolinx

Author: laujan

articles/ai-services/language-service/question-answering/concepts/best-practices.md

@@ -5,7 +5,7 @@ ms.service: azure-ai-language
 author: laujan
 ms.author: lajanuar
 ms.topic: conceptual
-ms.date: 07/16/2025
+ms.date: 07/17/2025
 ms.custom: language-service-question-answering
 ---
 
@@ -19,15 +19,15 @@ Custom question answering is continually improving the algorithms that extract q
 
 ## Creating good questions and answers
 
-We've used the following list of question and answer pairs as representation of a project to highlight best practices when authoring projects for custom question answering.
+We use the following list of question and answer pairs to represent a project. This approach helps highlight best practices when creating projects for custom question answering.
 
 | Question | Answer |
 |----------|----------|
 | I want to buy a car |There are three options to buy a car.|
 | I want to purchase software license |Software license can be purchased online at no cost.|
 | What is the price of Microsoft stock? | $200. |
 | How to buy Microsoft Services | Microsoft services can be bought online.|
-| Want to sell car | Please send car pics and document.|
+| Want to sell car | Send car pics and document.|
 | How to get access to identification card? | Apply via company portal to get identification card.|
 
 ### When should you add alternate questions to question and answer pairs?
@@ -45,55 +45,55 @@ The service can return the expected response for semantically similar queries su
 "What is the market value of a Microsoft stock?"
 "What is the market value of a Microsoft share?"
 
-However, it's important to understand that the confidence score with which the system returns the correct response will vary based on the input query and how different it is from the original question answer pair.  
+The confidence score that the system assigns to its response can vary. This variation depends on the input query and how much it differs from the original question-answer pair. 
 
-There are certain scenarios that require the customer to add an alternate question. When it's already verified that for a particular query the correct answer isn't returned despite being present in the project, we advise adding that query as an alternate question to the intended question answer pair.
+There are certain scenarios that require the customer to add an alternate question. If you already verified that a specific query doesn't return the correct answer, even though the answer exists in the project, we recommend taking further action. Add that query as an alternate question to the intended question and answer pair. This step can help ensure users receive the correct response in the future.
 
 ### How many alternate questions per question answer pair is optimal?
 
-Users can add as many alternate questions as they want, but only first 5 will be considered for core ranking. However, the rest will be useful for exact match scenarios. It is also recommended to keep the different intent/distinct alternate questions at the top for better relevance and score.
+Users can add as many alternate questions as they want, but only first 5 are considered for core ranking. However, the rest is useful for exact match scenarios. We also recommended keeping the different intent/distinct alternate questions at the top for better relevance and score.
 
 Semantic understanding in custom question answering should be able to take care of similar alternate questions.
 
-The return on investment will start diminishing once you exceed 10 questions. Even if you're adding more than 10 alternate questions, try to make the initial 10 questions as semantically dissimilar as possible so that all kinds of intents for the answer are captured by these 10 questions.  For the project at the beginning of this section, in question answer pair #1, adding alternate questions such as "How can I buy a car", "I wanna buy a car" aren't required. Whereas adding alternate questions such as "How to purchase a car", "What are the options of buying a vehicle" can be useful.
+The return on investment decreases after you exceed 10 questions. Even if you include more than 10 alternate questions, focus on making the first 10 questions as semantically different as possible. By doing so, you ensure that these 10 questions capture all possible intents for the answer. For the project at the beginning of this section, in question answer pair #1, adding alternate questions such as *How can I buy a car* or *I want to buy a car* aren't required. Whereas adding alternate questions such as *How to purchase a car*, *What are the options of buying a vehicle* can be useful.
 
 ### When to add synonyms to a project?
 
 Custom question answering provides the flexibility to use synonyms at the project level, unlike QnA Maker where synonyms are shared across projects for the entire service.
 
-For better relevance, you need to provide a list of acronyms that the end user intends to use interchangeably. The following is a list of acceptable acronyms:
+For better relevance, you need to provide a list of acronyms that the end user intends to use interchangeably. The following list details acceptable acronyms:
 
 * `MSFT` – Microsoft
 * `ID` – Identification
 * `ETA` – Estimated time of Arrival
 
-Other than acronyms, if you think your words are similar in context of a particular domain and generic language models won't consider them similar, it's better to add them as synonyms. For instance, if an auto company producing a car model X receives queries such as "my car's audio isn't working" and the project has questions on "fixing audio for car X", then we need to add 'X' and 'car' as synonyms.
+Other than acronyms, if you think your words are similar in context of a particular domain and generic language models doesn't consider them similar, it's better to add them as synonyms. For instance, an auto company producing a car model X receives queries such as *my car's audio isn't working* and the project has questions on *fixing audio for car X*. Then, we need to add 'X' and 'car' as synonyms.
 
-The transformer-based model already takes care of most of the common synonym cases, for example: `Purchase – Buy`, `Sell - Auction`, `Price – Value`. For another example, consider the following question answer pair: Q: "What is the price of Microsoft Stock?" A: "$200".  
+The transformer-based model already takes care of most of the common synonym cases, for example: `Purchase – Buy`, `Sell - Auction`, `Price – Value`. For another example, consider the following question answer pair: Q: *What is the price of Microsoft Stock?* A: *$200*. 
 
-If we receive user queries like "Microsoft stock value"," Microsoft share value", "Microsoft stock worth", "Microsoft share worth", "stock value", etc., you should be able to get the correct answer even though these queries have words like "share", "value", and "worth", which aren't originally present in the project.
+If users ask questions like *Microsoft stock value*, *Microsoft share value*, *Microsoft stock worth*, *Microsoft share worth*, or just *stock value*, you should still be able to provide the correct answer. It's important to maintain this clarity, even though terms such as *share*, *value*, and *worth* aren't originally included in the project.
 
-Special characters are not allowed in synonyms.
+Special characters aren't allowed in synonyms.
 
 ### How are lowercase/uppercase characters treated?
 
 Question answering takes casing into account but it's intelligent enough to understand when it's to be ignored. You shouldn't be seeing any perceivable difference due to wrong casing.
 
 ### How are question answer pairs prioritized for multi-turn questions?
 
-When a project has hierarchical relationships (either added manually or via extraction) and the previous response was an answer related to other question answer pairs, for the next query we give slight preference to all the children question answer pairs, sibling question answer pairs, and grandchildren question answer pairs in that order. Along with any query, the [custom question answering REST API](/rest/api/questionanswering/question-answering/get-answers) expects a `context` object with the property `previousQnAId`, which denotes the last top answer. Based on this previous `QnAID`, all the related `QnAs` are boosted.
+When a project includes hierarchical relationships—whether they're added manually or through extraction—special handling is applied. If the previous response addressed a question that belongs to a related set of question-answer pairs, it affects how we handle subsequent queries. For the next query, we give slight preference to all child question-answer pairs first. Preference is then given to sibling question-answer pairs, followed by grandchild question-answer pairs, in that order. Along with any query, the [custom question answering REST API](/rest/api/questionanswering/question-answering/get-answers) expects a `context` object with the property `previousQnAId`, which denotes the last top answer. Based on this previous `QnAID`, all the related `QnAs` are boosted.
 
 ### How are accents treated?
 
-Accents are supported for all major European languages. If the query has an incorrect accent, the confidence score might be slightly different, but the service still returns the relevant answer and takes care of minor errors by leveraging fuzzy search.
+Accents are supported for all major European languages. If the query has an incorrect accent, the confidence score might be slightly different, but the service still returns the relevant answer and takes care of minor errors by using fuzzy search.
 
 ### How is punctuation in a user query treated?
 
 Punctuation is ignored in a user query before sending it to the ranking stack. Ideally it shouldn't impact the relevance scores. Punctuation that is ignored is as follows:  `,?:;\"'(){}[]-+。./!*؟`
 
 ## Chit-Chat
 
-Add chit-chat to your bot, to make your bot more conversational and engaging, with low effort. You can easily add chit-chat data sources from pre-defined personalities when creating your project, and change them at any time. Learn how to [add chit-chat to your KB](../How-To/chit-chat.md).
+Add chit-chat to your bot, to make your bot more conversational and engaging, with low effort. You can easily add chit-chat data sources from predefined personalities when creating your project, and change them at any time. Learn how to [add chit-chat to your KB](../How-To/chit-chat.md).
 
 Chit-chat is supported in [many languages](../how-to/chit-chat.md#language-support).
 
@@ -113,15 +113,14 @@ The responses range from formal to informal and irreverent. You should select th
 
 ### Edit bot-specific questions
 
-There are some bot-specific questions that are part of the chit-chat data set, and have been filled in with generic answers. Change these answers to best reflect your bot details.
+There are some bot-specific questions that are part of the chit-chat data set, and are completed with generic answers. Change these answers to best reflect your bot details.
 
 We recommend making the following chit-chat question answer pairs more specific:
 
 * Who are you?
 * What can you do?
-* How old are you?
+* What is your age?
 * Who created you?
-* Hello
 
 ### Adding custom chit-chat with a metadata tag
 
@@ -135,11 +134,11 @@ The custom question answering REST API uses both questions and the answer to sea
 
 Use the [`RankerType=QuestionOnly`](#choosing-ranker-type) if you don't want to search answers.
 
-An example of this is when the project is a catalog of acronyms as questions with their full form as the answer. The value of the answer won't help to search for the appropriate answer.
+An example is when the project is a catalog of acronyms as questions with their full form as the answer. The value of the answer doesn't help to search for the appropriate answer.
 
 ## Ranking/Scoring
 
-Make sure you're making the best use of the supported ranking features. Doing so will improve the likelihood that a given user query is answered with an appropriate response.
+Make sure you're making the best use of the supported ranking features. Doing so improves the likelihood that a given user query is answered with an appropriate response.
 
 ### Choosing a threshold
 
@@ -151,7 +150,7 @@ By default, custom question answering searches through questions and answers. If
 
 ### Add alternate questions
 
-Alternate questions to improve the likelihood of a match with a user query. Alternate questions are useful when there are multiple ways in which the same question may be asked. This can include changes in the sentence structure and word-style.
+Alternate questions to improve the likelihood of a match with a user query. Alternate questions are useful when there are multiple ways in which the same question may be asked. The alternate questions can include changes in the sentence structure and word-style.
 
 |Original query|Alternate queries|Change|
 |--|--|--|
@@ -160,15 +159,15 @@ Alternate questions to improve the likelihood of a match with a user query. Alte
 
 ### Use metadata tags to filter questions and answers
 
-Metadata adds the ability for a client application to know it shouldn't take all answers but instead to narrow down the results of a user query based on metadata tags. The project answer can differ based on the metadata tag, even if the query is the same. For example, *"where is parking located"* can have a different answer if the location of the restaurant branch is different - that is, the metadata is *Location: Seattle* versus *Location: Redmond*.
+Metadata adds the ability for a client application to know it shouldn't take all answers but instead to narrow down the results of a user query based on metadata tags. The project answer can differ based on the metadata tag, even if the query is the same. For example, the answer to *where is parking located* can vary depending on the branch location. If the metadata is *Location: Seattle*, the answer is different than if the metadata is *Location: Redmond*.
 
 ### Use synonyms
 
 While there's some support for synonyms in the English language, use case-insensitive [word alterations](../tutorials/adding-synonyms.md) to add synonyms to keywords that take different forms.
 
 |Original word|Synonyms|
 |--|--|
-|buy|purchase<br>net-banking<br>net banking|
+|buy|purchase<br>Net-banking<br>Net banking|
 
 ---
 
@@ -183,11 +182,11 @@ For example, you might have two separate question answer pairs with the followin
 |where is the parking *location*|
 |where is the ATM *location*|
 
-Since these two questions are phrased with very similar words, this similarity could cause very similar scores for many user queries that are phrased like  *"where is the `<x>` location"*. Instead, try to clearly differentiate with queries like  *"where is the parking lot"* and *"where is the ATM"*, by avoiding words like "location" that could be in many questions in your project.
+Since these two questions are phrased with similar words, this similarity could cause similar scores for many user queries that are phrased like  *where is the `<x>` location*. Instead, try to clearly differentiate your queries. For example, use specific questions like *where is the parking lot* and *where is the ATM*. Avoid using general words like *location*, since they could appear in many different questions throughout your project.
 
 ## Collaborate
 
-Custom question answering allows users to collaborate on a project. Users need access to the associated Azure resource group in order to access the projects. Some organizations may want to outsource the project editing and maintenance, and still be able to protect access to their Azure resources. This editor-approver model is done by setting up two identical language resources with identical custom question answering projects in different subscriptions and selecting one for the edit-testing cycle. Once testing is finished, the project contents are exported and transferred with an [import-export](../how-to/migrate-knowledge-base.md) process to the language resource of the approver that will finally deploy the project and update the endpoint.
+Custom question answering allows users to collaborate on a project. Users need access to the associated Azure resource group in order to access the projects. Some organizations may want to outsource the project editing and maintenance, and still be able to protect access to their Azure resources. This editor-approver model is done by setting up two identical language resources with identical custom question answering projects in different subscriptions and selecting one for the edit-testing cycle. Once testing is finished, the project contents are exported. They're then transferred using an [import-export](../how-to/migrate-knowledge-base.md) process. This process moves the contents to the language resource of the approver, who deploys the project and updates the endpoint.
 
 ## Active learning
 

articles/ai-services/qnamaker/toc.yml

@@ -146,7 +146,7 @@ items:
     - name: QnA Maker 5.0 Preview 1
       href: /rest/api/qnamaker/alterations?view=rest-qnamaker-v5.0-preview.1&preserve-view=true
     - name: QnA Maker 5.0 Preview 2
-      href: /rest/api/qnamaker/alterations?view=rest-qnamaker-v5.0-preview.2
+      href: /rest/api/qnamaker/alterations?view=rest-qnamaker-v5.0-preview.2&preserve-view=true
   - name: SDKs
     items:
     - name: C#