acrolinx

Author: laujan

articles/ai-services/qnamaker/concepts/best-practices.md

@@ -30,26 +30,26 @@ In general, FAQ pages should be stand-alone and not combined with other informat
 
 ### Good questions
 
-The best questions are simple. Consider the key word or phrase for each question then create a simple question for that key word or phrase.
+The best questions are simple. Consider the key word or phrase for each question then create a basic question for that key word or phrase.
 
-Add as many alternate questions as you need but keep the alterations simple. Adding more words or phrasings that are not part of the main goal of the question does not help QnA Maker find a match.
+Add as many alternate questions as you need but keep the alterations simple. Adding more words or phrasings that aren't part of the main goal of the question doesn't help QnA Maker find a match.
 
 
 ### Add relevant alternative questions
 
-Your user may enter questions with either a conversational style of text, `How do I add a toner cartridge to my printer?` or a keyword search such as `toner cartridge`. The knowledge base should have both styles of questions in order to correctly return the best answer. If you aren't sure what keywords a customer is entering, use Application Insights data to analyze queries.
+Your user may enter questions with either a conversational style of text, `How do I add a toner cartridge to my printer?` or, a keyword search such as `toner cartridge`. The knowledge base should have both styles of questions in order to correctly return the best answer. If you aren't sure what keywords a customer is entering, use Application Insights data to analyze queries.
 
 ### Good answers
 
-The best answers are simple answers but not too simple. Do not use answers such as `yes` and `no`. If your answer should link to other sources or provide a rich experience with media and links, use [metadata tagging](../how-to/edit-knowledge-base.md#add-metadata) to distinguish between answers, then [submit the query](../how-to/metadata-generateanswer-usage.md#generateanswer-request-configuration) with metadata tags in the `strictFilters` property to get the correct answer version.
+The best answers are simple answers but not too simple. Don't use answers such as `yes` and `no`. If your answer should link to other sources or provide a rich experience with media and links, use [metadata tagging](../how-to/edit-knowledge-base.md#add-metadata) to distinguish between answers, then [submit the query](../how-to/metadata-generateanswer-usage.md#generateanswer-request-configuration) with metadata tags in the `strictFilters` property to get the correct answer version.
 
 |Answer|Follow-up prompts|
 |--|--|
 |Power down the Surface laptop with the power button on the keyboard.|* Key-combinations to sleep, shut down, and restart.<br>* How to hard-boot a Surface laptop<br>* How to change the BIOS for a Surface laptop<br>* Differences between sleep, shut down and restart|
 |Customer service is available via phone, Skype, and text message 24 hours a day.|* Contact information for sales.<br> * Office and store locations and hours for an in-person visit.<br> * Accessories for a Surface laptop.|
 
 ## 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 sets from pre-defined personalities when creating your KB, and change them at any time. Learn how to [add chit-chat to your KB](../how-to/chit-chat-knowledge-base.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 sets from predefined personalities when creating your KB, and change them at any time. Learn how to [add chit-chat to your KB](../how-to/chit-chat-knowledge-base.md).
 
 Chit-chat is supported in [many languages](../how-to/chit-chat-knowledge-base.md#language-support).
 
@@ -67,7 +67,7 @@ Chit-chat is supported for several predefined personalities:
 The responses range from formal to informal and irreverent. Select the personality that is closest aligned with the tone you want for your bot. 
 
 ### 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 filled in with generic answers. Change these answers to best reflect your bot details.
 
 We recommend making the following chit-chat QnAs more specific:
 
@@ -85,14 +85,14 @@ If you add your own chit-chat QnA pairs, make sure to add metadata so these answ
 
 GenerateAnswer API uses both questions and the answer to search for best answers to a user's query.
 
-### Searching questions only when answer is not relevant
+### Searching questions only when answer isn't relevant
 
 Use the [`RankerType=QuestionOnly`](#choosing-ranker-type) if you don't want to search answers.
 
-An example of this, is when the knowledge base is a catalog of acronyms as questions with their full form as the answer. The value of the answer will not help to search for the appropriate answer.
+An example is when the knowledge base is a catalog of acronyms as questions with their full form as the answer. The value of the answer doesn't help find the appropriate answer.
 
 ## Ranking/Scoring
-Make sure you are making the best use of the ranking features QnA Maker supports. 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 ranking features QnA Maker supports. Doing so improves the likelihood that a given user query is answered with an appropriate response.
 
 ### Choosing a threshold
 
@@ -102,7 +102,7 @@ The default [confidence score](confidence-score.md) that is used as a threshold
 By default, QnA Maker searches through questions and answers. If you want to search through questions only, to generate an answer, use the `RankerType=QuestionOnly` in the POST body of the GenerateAnswer request.
 
 ### Add alternate questions
-[Alternate questions](../how-to/edit-knowledge-base.md) 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](../how-to/edit-knowledge-base.md) 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 approach can include changes in the sentence structure and word-style.
 
 |Original query|Alternate queries|Change|
 |--|--|--|
@@ -113,14 +113,14 @@ By default, QnA Maker searches through questions and answers. If you want to sea
 
 ### Use metadata tags to filter questions and answers
 
-[Metadata](../how-to/edit-knowledge-base.md) adds the ability for a client application to know it should not take all answers but instead to narrow down the results of a user query based on metadata tags. The knowledge base 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](../how-to/edit-knowledge-base.md) 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 knowledge base 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*.
 
 ### Use synonyms
 
-While there is some support for synonyms in the English language, use case-insensitive word alterations via the [Alterations API](/rest/api/qnamaker/alterations/replace) to add synonyms to keywords that take different forms. Synonyms are added at the QnA Maker service-level and **shared by all knowledge bases in the service**.
+While there's some support for synonyms in the English language, use case-insensitive word alterations via the [Alterations API](/rest/api/qnamaker/alterations/replace) to add synonyms to keywords that take different forms. Synonyms are added at the QnA Maker service-level and **shared by all knowledge bases in the service**.
 
 ### Use distinct words to differentiate questions
-QnA Maker's ranking algorithm, that matches a user query with a question in the knowledge base, works best if each question addresses a different need. Repetition of the same word set between questions reduces the likelihood that the right answer is chosen for a given user query with those words.
+QnA Maker's ranking algorithm that matches a user query with a question in the knowledge base works best if each question addresses a different need. Repetition of the same word set between questions reduces the likelihood that the right answer is chosen for a given user query with those words.
 
 For example, you might have two separate QnAs with the following questions:
 
@@ -129,14 +129,14 @@ For example, you might have two separate QnAs with the following questions:
 |where is the parking *location*|
 |where is the ATM *location*|
 
-Since these two QnAs 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 KB.
+Since these two QnAs 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 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 KB.
 
 ## Collaborate
-QnA Maker allows users to collaborate on a knowledge base. Users need access to the Azure AI QnA Maker resource group in order to access the knowledge bases. Some organizations may want to outsource the knowledge base 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 [QnA Maker services](../How-to/set-up-qnamaker-service-azure.md) in different subscriptions and selecting one for the edit-testing cycle. Once testing is finished, the knowledge base contents are transferred with an [import-export](../tutorials/export-knowledge-base.md) process to the QnA Maker service of the approver that will finally publish the knowledge base and update the endpoint.
+QnA Maker allows users to collaborate on a knowledge base. Users need access to the Azure AI QnA Maker resource group in order to access the knowledge bases. Some organizations may want to outsource the knowledge base 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 [QnA Maker services](../How-to/set-up-qnamaker-service-azure.md) in different subscriptions and selecting one for the edit-testing cycle. Once testing is finished, the knowledge base contents are transferred with an [import-export](../tutorials/export-knowledge-base.md) process to the QnA Maker service of the approver that finally publishes the knowledge base and update the endpoint.
 
 ## Active learning
 
-[Active learning](../How-to/use-active-learning.md) does the best job of suggesting alternative questions when it has a wide range of quality and quantity of user-based queries. It is important to allow client-applications' user queries to participate in the active learning feedback loop without censorship. Once questions are suggested in the QnA Maker portal, you can **[filter by suggestions](../how-to/improve-knowledge-base.md)** then review and accept or reject those suggestions.
+[Active learning](../How-to/use-active-learning.md) does the best job of suggesting alternative questions when it has a wide range of quality and quantity of user-based queries. It's important to allow client-applications' user queries to participate in the active learning feedback loop without censorship. Once questions are suggested in the QnA Maker portal, you can **[filter by suggestions](../how-to/improve-knowledge-base.md)** then review and accept or reject those suggestions.
 
 ## Next steps