Merge pull request #111308 from diberry/diberry/0414-luis-grammar

[Cogsvcs] LUIS - app settings

Author: Jak-MS

articles/cognitive-services/LUIS/get-started-portal-build-app.md

@@ -2,7 +2,7 @@
 title: "Quickstart: Create a new app in the LUIS portal"
 description: In this quickstart, you create the basic parts of an app, intents, and entities as well as test with sample utterance in the LUIS portal.
 ms.topic: quickstart
-ms.date: 03/24/2020
+ms.date: 04/14/2020
 #Customer intent: As a new user, I want to quickly get a LUIS app created in the LUIS portal so I can understand the different models of intent, entity, and example utterances.
 ---
 
@@ -84,13 +84,12 @@ Add the following 15 example utterances to the `FindForm` intent.
 By design, these example utterances vary in the following ways:
 
 * utterance length
-* punctuation
+* [punctuation](luis-reference-application-settings.md#punctuation-normalization)
 * word choice
 * verb tense (is, was, will be)
 * word order
 
 
-
 ## Create a regular expression entity
 
 To return the form number in the runtime prediction response, the form must be marked as an entity. Because the form number text is highly structured, you can mark it using a regular expression entity. Create the entity with the following steps:

articles/cognitive-services/LUIS/includes/do-not-use-too-few-utterances.md

@@ -6,11 +6,11 @@ author: diberry
 manager: nitinme
 ms.custom: seodec18
 ms.service: cognitive-services
-ms.date: 02/14/2020
+ms.date: 04/14/2020
 ms.subservice: language-understanding
 ms.topic: include
 ms.custom: include file
 ms.author: diberry
 ---
 
-These few utterances are for demonstration purposes only. A real-world app should have at least 15 utterances of varying length, word order, tense, grammatical correctness, punctuation, and word count.
+These few utterances are for demonstration purposes only. A real-world app should have at least 15 utterances of varying length, word order, tense, grammatical correctness, [punctuation](../luis-reference-application-settings.md#punctuation-normalization), and word count.

articles/cognitive-services/LUIS/label-entity-example-utterance.md

@@ -1,15 +1,8 @@
 ---
 title: Label entity example utterance
-titleSuffix: Azure Cognitive Services
 description: Learn how to label a machine-learned entity with subcomponents in an example utterance in an intent detail page of the LUIS portal.
-services: cognitive-services
-author: diberry
-manager: nitinme
-ms.service: cognitive-services
-ms.subservice: language-understanding
 ms.topic: conceptual
-ms.date: 12/16/2019
-ms.author: diberry
+ms.date: 04/14/2020
 #Customer intent: As a new user, I want to label a machine-learned entity in an example utterance.
 ---
 
@@ -84,6 +77,10 @@ Entity roles are labeled using the entity palette.
 1. Move to the **Entity inspector**, and either select an existing role or create a new role.
 1. In the example utterance text, label the text with the entity role.
 
+## Labeling for punctuation
+
+You do not need to label for punctuation. Use [application settings](luis-reference-application-settings.md) to control if punctuation impacts utterance predictions.
+
 ## Unlabel entities
 
 To unlabel an entity, select the entity name underneath the text and select **Unlabel**. If the entity you are trying to unlabel has labeled subcomponents, then the subcomponents must be unlabeled first.

articles/cognitive-services/LUIS/luis-concept-best-practices.md

@@ -1,28 +1,21 @@
 ---
 title: Best practices for building your LUIS app
-titleSuffix: Azure Cognitive Services
 description: Learn the best practices to get the best results from your LUIS app's model.
-services: cognitive-services
-author: diberry
-manager: nitinme
-ms.custom: seodec18
-ms.service: cognitive-services
-ms.subservice: language-understanding
 ms.topic: conceptual
-ms.date: 10/25/2019
+ms.date: 04/14/2020
 ms.author: diberry
 ---
 # Best practices for building a language understanding (LUIS) app
-Use the app authoring process to build your LUIS app: 
+Use the app authoring process to build your LUIS app:
 
 * Build language models (intents and entities)
 * Add a few training example utterances (15-30 per intent)
 * Publish to endpoint
-* Test from endpoint 
+* Test from endpoint
 
-Once your app is [published](luis-how-to-publish-app.md), use the development lifecycle to add features, publish, and test from endpoint. Do not begin the next authoring cycle by adding more example utterances because that does not let LUIS learn your model with real-world user utterances. 
+Once your app is [published](luis-how-to-publish-app.md), use the development lifecycle to add features, publish, and test from endpoint. Do not begin the next authoring cycle by adding more example utterances because that does not let LUIS learn your model with real-world user utterances.
 
-Do not expand the utterances until the current set of both example and endpoint utterances are returning confident, high prediction scores. Improve scores using [active learning](luis-concept-review-endpoint-utterances.md). 
+Do not expand the utterances until the current set of both example and endpoint utterances are returning confident, high prediction scores. Improve scores using [active learning](luis-concept-review-endpoint-utterances.md).
 
 
 
@@ -43,7 +36,7 @@ The following list includes best practices for LUIS apps:
 ## Do define distinct intents
 Make sure the vocabulary for each intent is just for that intent and not overlapping with a different intent. For example, if you want to have an app that handles travel arrangements such as airline flights and hotels, you can choose to have these subject areas as separate intents or the same intent with entities for specific data inside the utterance.
 
-If the vocabulary between two intents is the same, combine the intent, and use entities. 
+If the vocabulary between two intents is the same, combine the intent, and use entities.
 
 Consider the following example utterances:
 
@@ -52,20 +45,20 @@ Consider the following example utterances:
 |Book a flight|
 |Book a hotel|
 
-`Book a flight` and `Book a hotel` use the same vocabulary of `book a `. This format is the same so it should be the same intent with the different words of `flight` and `hotel` as extracted entities. 
+`Book a flight` and `Book a hotel` use the same vocabulary of `book a `. This format is the same so it should be the same intent with the different words of `flight` and `hotel` as extracted entities.
 
 ## Do add descriptors to intents
 
-Descriptors help describe features for an intent. A descriptor can be a phrase list of words that are significant to that intent or an entity that is significant to that intent. 
+Descriptors help describe features for an intent. A descriptor can be a phrase list of words that are significant to that intent or an entity that is significant to that intent.
 
 ## Do find sweet spot for intents
-Use prediction data from LUIS to determine if your intents are overlapping. Overlapping intents confuse LUIS. The result is that the top scoring intent is too close to another intent. Because LUIS does not use the exact same path through the data for training each time, an overlapping intent has a chance of being first or second in training. You want the utterance's score for each intention to be farther apart so this flip/flop doesn't happen. Good distinction for intents should result in the expected top intent every time. 
- 
+Use prediction data from LUIS to determine if your intents are overlapping. Overlapping intents confuse LUIS. The result is that the top scoring intent is too close to another intent. Because LUIS does not use the exact same path through the data for training each time, an overlapping intent has a chance of being first or second in training. You want the utterance's score for each intention to be farther apart so this flip/flop doesn't happen. Good distinction for intents should result in the expected top intent every time.
+
 <a name="#do-build-the-app-iteratively"></a>
 
 ## Do build your app iteratively with versions
 
-Each authoring cycle should be within a new [version](luis-concept-version.md), cloned from an existing version. 
+Each authoring cycle should be within a new [version](luis-concept-version.md), cloned from an existing version.
 
 ## Do build for model decomposition
 
@@ -76,58 +69,33 @@ Model decomposition has a typical process of:
 * label top-level data concept in example utterance
 * break data concept into subcomponents
 * add descriptors (features) to subcomponents
-* add descriptors (features) to intent 
+* add descriptors (features) to intent
 
-Once you have created the intent and added example utterances, the following example describes entity decomposition. 
+Once you have created the intent and added example utterances, the following example describes entity decomposition.
 
-Start by identifying complete data concepts you want to extract in an utterance. This is your machine-learned entity. Then decompose the phrase into its parts. This includes identifying subcomponents (as entities), along with descriptors and constraints. 
+Start by identifying complete data concepts you want to extract in an utterance. This is your machine-learned entity. Then decompose the phrase into its parts. This includes identifying subcomponents (as entities), along with descriptors and constraints.
 
-For example if you want to extract an address, the top machine-learned entity could be called `Address`. While creating the address, identify some of its subcomponents such as street address, city, state, and postal code. 
+For example if you want to extract an address, the top machine-learned entity could be called `Address`. While creating the address, identify some of its subcomponents such as street address, city, state, and postal code.
 
 Continue decomposing those elements by **constraining** the postal code to a regular expression. Decompose the street address into parts of a street number (using a prebuilt number), a street name, and a street type. The street type can be described with a **descriptor** list such as avenue, circle, road, and lane.
 
-The V3 authoring API allows for model decomposition. 
+The V3 authoring API allows for model decomposition.
 
 ## Do add patterns in later iterations
 
-You should understand how the app behaves before adding [patterns](luis-concept-patterns.md) because patterns are weighted more heavily than example utterances and will skew confidence. 
-
-Once you understand how your app behaves, add patterns as they apply to your app. You do not need to add them with each [iteration](luis-concept-app-iteration.md). 
-
-There is no harm adding them in the beginning of your model design but it is easier to see how each pattern changes the model after the model is tested with utterances. 
- 
-<!--
-
-### Phrase lists
-
-[Phrase lists](luis-concept-feature.md) allow you to define dictionaries of words related to your app domain. Seed your phrase list with a few words then use the suggest feature so LUIS knows about more words in the vocabulary specific to your app. A Phrase List improves intent detection and entity classification by boosting the signal associated with words or phrases that are significant to your app. 
-
-Don't add every word to the vocabulary since the phrase list isn't an exact match. 
-
-For more information:
-* Concept: [Phrase list features in your LUIS app](luis-concept-feature.md)
-* How-to: [Use phrase lists to boost signal of word list](luis-how-to-add-features.md)
-
-
-
-### Patterns
-
-Real user utterances from the endpoint, very similar to each other, may reveal patterns of word choice and placement. The [pattern](luis-concept-patterns.md) feature takes this word choice and placement along with regular expressions to improve your prediction accuracy. A regular expression in the pattern allows for words and punctuation you intend to ignore while still matching the pattern. 
+You should understand how the app behaves before adding [patterns](luis-concept-patterns.md) because patterns are weighted more heavily than example utterances and will skew confidence.
 
-Use pattern's [optional syntax](luis-concept-patterns.md) for punctuation so punctuation can be ignored. Use the [explicit list](luis-concept-patterns.md#explicit-lists) to compensate for pattern.any syntax issues. 
+Once you understand how your app behaves, add patterns as they apply to your app. You do not need to add them with each [iteration](luis-concept-app-iteration.md).
 
-For more information:
-* Concept: [Patterns improve prediction accuracy](luis-concept-patterns.md)
-* How-to: [How to add Patterns to improve prediction accuracy](luis-how-to-model-intent-pattern.md)
--->
+There is no harm adding them in the beginning of your model design but it is easier to see how each pattern changes the model after the model is tested with utterances.
 
 <a name="balance-your-utterances-across-all-intents"></a>
 
 ## Do balance your utterances across all intents
 
-In order for LUIS predictions to be accurate, the quantity of example utterances in each intent (except for the None intent), must be relatively equal. 
+In order for LUIS predictions to be accurate, the quantity of example utterances in each intent (except for the None intent), must be relatively equal.
 
-If you have an intent with 100 example utterances and an intent with 20 example utterances, the 100-utterance intent will have a higher rate of prediction.  
+If you have an intent with 100 example utterances and an intent with 20 example utterances, the 100-utterance intent will have a higher rate of prediction.
 
 ## Do add example utterances to None intent
 
@@ -139,49 +107,49 @@ Use [active learning](luis-how-to-review-endpoint-utterances.md)'s **Review endp
 
 ## Do monitor the performance of your app
 
-Monitor the prediction accuracy using a [batch test](luis-concept-batch-test.md) set. 
+Monitor the prediction accuracy using a [batch test](luis-concept-batch-test.md) set.
 
-Keep a separate set of utterances that aren't used as [example utterances](luis-concept-utterance.md) or endpoint utterances. Keep improving the app for your test set. Adapt the test set to reflect real user utterances. Use this test set to evaluate each iteration or version of the app. 
+Keep a separate set of utterances that aren't used as [example utterances](luis-concept-utterance.md) or endpoint utterances. Keep improving the app for your test set. Adapt the test set to reflect real user utterances. Use this test set to evaluate each iteration or version of the app.
 
 ## Don't add many example utterances to intents
 
-After the app is published, only add utterances from active learning in the development lifecycle process. If utterances are too similar, add a pattern. 
+After the app is published, only add utterances from active learning in the development lifecycle process. If utterances are too similar, add a pattern.
 
 ## Don't use few or simple entities
 
-Entities are built for data extraction and prediction. It is important that each intent have machine-learned entities that describe the data in the intent. This helps LUIS predict the intent, even if your client application doesn't need to use the extracted entity. 
+Entities are built for data extraction and prediction. It is important that each intent have machine-learned entities that describe the data in the intent. This helps LUIS predict the intent, even if your client application doesn't need to use the extracted entity.
 
 ## Don't use LUIS as a training platform
 
-LUIS is specific to a language model's domain. It isn't meant to work as a general natural language training platform. 
+LUIS is specific to a language model's domain. It isn't meant to work as a general natural language training platform.
 
 ## Don't add many example utterances of the same format, ignoring other formats
 
-LUIS expects variations in an intent's utterances. The utterances can vary while having the same overall meaning. Variations can include utterance length, word choice, and word placement. 
+LUIS expects variations in an intent's utterances. The utterances can vary while having the same overall meaning. Variations can include utterance length, word choice, and word placement.
 
 |Don't use same format|Do use varying format|
 |--|--|
 |Buy a ticket to Seattle<br>Buy a ticket to Paris<br>Buy a ticket to Orlando|Buy 1 ticket to Seattle<br>Reserve two seats on the red eye to Paris next Monday<br>I would like to book 3 tickets to Orlando for spring break|
 
-The second column uses different verbs (buy, reserve, book), different quantities (1, two, 3), and different arrangements of words but all have the same intention of purchasing airline tickets for travel. 
+The second column uses different verbs (buy, reserve, book), different quantities (1, two, 3), and different arrangements of words but all have the same intention of purchasing airline tickets for travel.
 
 ## Don't mix the definition of intents and entities
 
-Create an intent for any action your bot will take. Use entities as parameters that make that action possible. 
+Create an intent for any action your bot will take. Use entities as parameters that make that action possible.
 
-For a bot that will book airline flights, create a **BookFlight** intent. Do not create an intent for every airline or every destination. Use those pieces of data as [entities](luis-concept-entity-types.md) and mark them in the example utterances. 
+For a bot that will book airline flights, create a **BookFlight** intent. Do not create an intent for every airline or every destination. Use those pieces of data as [entities](luis-concept-entity-types.md) and mark them in the example utterances.
 
 ## Don't create descriptors with all the possible values
 
-Provide a few examples in the descriptor [phrase lists](luis-concept-feature.md) but not every word. LUIS generalizes and takes context into account. 
+Provide a few examples in the descriptor [phrase lists](luis-concept-feature.md) but not every word. LUIS generalizes and takes context into account.
 
 ## Don't add many patterns
 
 Don't add too many [patterns](luis-concept-patterns.md). LUIS is meant to learn quickly with fewer examples. Don't overload the system unnecessarily.
 
 ## Don't train and publish with every single example utterance
 
-Add 10 or 15 utterances before training and publishing. That allows you to see the impact on prediction accuracy. Adding a single utterance may not have a visible impact on the score. 
+Add 10 or 15 utterances before training and publishing. That allows you to see the impact on prediction accuracy. Adding a single utterance may not have a visible impact on the score.
 
 ## Next steps