fix rank and reward language

Author: diberry

articles/cognitive-services/personalizer/includes/change-model-frequency.md

@@ -0,0 +1,20 @@
+---
+title: include file
+description: include file
+services: cognitive-services
+author: diberry
+manager: nitinme
+ms.service: cognitive-services
+ms.subservice: personalizer
+ms.topic: include
+ms.custom: include file
+ms.date: 01/15/2020
+ms.author: diberry
+---
+## Change the model update frequency
+
+In the Azure portal, in the Personalizer resource on the **Configuration** page, change the **Model update frequency** to 10 seconds. This short duration will train the service rapidly, allowing you to see how the top action changes for each iteration.
+
+![Change model update frequency](../media/settings/configure-model-update-frequency-settings.png)
+
+When a Personalizer loop is first instantiated, there is no model since there has been no Reward API calls to train from. Rank calls will return equal probabilities for each item. Your application should still always rank content using the output of RewardActionId.

articles/cognitive-services/personalizer/includes/create-personalizer-resource.md

@@ -0,0 +1,26 @@
+---
+title: include file
+description: include file
+services: cognitive-services
+author: diberry
+manager: nitinme
+ms.service: cognitive-services
+ms.subservice: personalizer
+ms.topic: include
+ms.custom: include file
+ms.date: 01/15/2020
+ms.author: diberry
+---
+## Create a Personalizer Azure resource
+
+Create a resource for Personalizer using the [Azure portal](https://docs.microsoft.com/azure/cognitive-services/cognitive-services-apis-create-account) or [Azure CLI](https://docs.microsoft.com/azure/cognitive-services/cognitive-services-apis-create-account-cli) on your local machine. You can also:
+
+* Get a [trial key](https://azure.microsoft.com/try/cognitive-services) valid for 7 days for free. After signing up, it will be available on the [Azure website](https://azure.microsoft.com/try/cognitive-services/my-apis/).
+* View your resource on the [Azure portal](https://portal.azure.com/).
+
+After you get a key from your trial subscription or resource, create two [environment variable](https://docs.microsoft.com/azure/cognitive-services/cognitive-services-apis-create-account#configure-an-environment-variable-for-authentication):
+
+* `PERSONALIZER_RESOURCE_KEY` for the resource key.
+* `PERSONALIZER_RESOURCE_ENDPOINT` for the resource endpoint.
+
+In the Azure portal, both the key and endpoint values are available from the **quickstart** page.

articles/cognitive-services/personalizer/includes/quickstart-sdk-csharp.md

@@ -23,32 +23,14 @@ ms.author: diberry
 There are several steps to use this quickstart:
 
 * In the Azure portal, create a Personalizer resource
-* In the Azure portal, for the Personalizer resource, on the **Configuration** page, change the model update frequency
+* In the Azure portal, for the Personalizer resource, on the **Configuration** page, change the model update frequency to a very short interval
 * In a code editor, create a code file and edit the code file
 * In the command line or terminal, install the SDK from the command line
 * In the command line or terminal, run the code file
 
-## Create a Personalizer Azure resource
+[!INCLUDE [Create Azure resource for Personalizer](create-personalizer-resource.md)]
 
-Create a resource for Personalizer using the [Azure portal](https://docs.microsoft.com/azure/cognitive-services/cognitive-services-apis-create-account) or [Azure CLI](https://docs.microsoft.com/azure/cognitive-services/cognitive-services-apis-create-account-cli) on your local machine. You can also:
-
-* Get a [trial key](https://azure.microsoft.com/try/cognitive-services) valid for 7 days for free. After signing up, it will be available on the [Azure website](https://azure.microsoft.com/try/cognitive-services/my-apis/).
-* View your resource on the [Azure portal](https://portal.azure.com/).
-
-After you get a key from your trial subscription or resource, create two [environment variable](https://docs.microsoft.com/azure/cognitive-services/cognitive-services-apis-create-account#configure-an-environment-variable-for-authentication):
-
-* `PERSONALIZER_RESOURCE_KEY` for the resource key.
-* `PERSONALIZER_RESOURCE_ENDPOINT` for the resource endpoint.
-
-In the Azure portal, both the key and endpoint values are available from the **quickstart** page.
-
-## Change the model update frequency
-
-In the Azure portal, in the Personalizer resource on the **Configuration** page, change the **Model update frequency** to 10 seconds. This short duration will train the service rapidly, allowing you to see how the top action changes for each iteration.
-
-![Change model update frequency](../media/settings/configure-model-update-frequency-settings.png)
-
-When a Personalizer loop is first instantiated, there is no model since there has been no Reward API calls to train from. Rank calls will return equal probabilities for each item. Your application should still always rank content using the output of RewardActionId.
+[!INCLUDE [!Change model frequency](change-model-frequency.md)]
 
 ## Create a new C# application
 
@@ -90,19 +72,19 @@ If you're using the Visual Studio IDE, the client library is available as a down
 
 The Personalizer client is a [PersonalizerClient](https://docs.microsoft.com/dotnet/api/microsoft.azure.cognitiveservices.personalizer.personalizerclient?view=azure-dotnet) object that authenticates to Azure using Microsoft.Rest.ServiceClientCredentials, which contains your key.
 
-To ask for a rank of the content, create a [RankRequest](https://docs.microsoft.com/dotnet/api/microsoft.azure.cognitiveservices.personalizer.models.rankrequest?view=azure-dotnet-preview), then pass it to [client.Rank](https://docs.microsoft.com/dotnet/api/microsoft.azure.cognitiveservices.personalizer.personalizerclientextensions.rank?view=azure-dotnet-preview) method. The Rank method returns a RankResponse, containing the ranked content.
+To ask for the single best item of the content, create a [RankRequest](https://docs.microsoft.com/dotnet/api/microsoft.azure.cognitiveservices.personalizer.models.rankrequest?view=azure-dotnet-preview), then pass it to [client.Rank](https://docs.microsoft.com/dotnet/api/microsoft.azure.cognitiveservices.personalizer.personalizerclientextensions.rank?view=azure-dotnet-preview) method. The Rank method returns a RankResponse.
 
-To send a reward to Personalizer, create a [RewardRequest](https://docs.microsoft.com/dotnet/api/microsoft.azure.cognitiveservices.personalizer.models.rewardrequest?view=azure-dotnet-preview), then pass it to the [client.Reward](https://docs.microsoft.com/dotnet/api/microsoft.azure.cognitiveservices.personalizer.personalizerclientextensions.reward?view=azure-dotnet-preview) method.
+To send a reward score to Personalizer, create a [RewardRequest](https://docs.microsoft.com/dotnet/api/microsoft.azure.cognitiveservices.personalizer.models.rewardrequest?view=azure-dotnet-preview), then pass it to the [client.Reward](https://docs.microsoft.com/dotnet/api/microsoft.azure.cognitiveservices.personalizer.personalizerclientextensions.reward?view=azure-dotnet-preview) method.
 
-Determining the reward, in this quickstart is trivial. In a production system, the determination of what impacts the [reward score](../concept-rewards.md) and by how much can be a complex process, that you may decide to change over time. This design decision should be one of the primary decisions in your Personalizer architecture.
+Determining the reward score, in this quickstart is trivial. In a production system, the determination of what impacts the [reward score](../concept-rewards.md) and by how much can be a complex process, that you may decide to change over time. This design decision should be one of the primary decisions in your Personalizer architecture.
 
 ## Code examples
 
 These code snippets show you how to do the following tasks with the Personalizer client library for .NET:
 
 * [Create a Personalizer client](#create-a-personalizer-client)
-* [Request a rank](#request-a-rank)
-* [Send a reward](#send-a-reward)
+* [Rank API](#request-the-best-action)
+* [Reward API](#send-a-reward)
 
 ## Add the dependencies
 
@@ -124,13 +106,13 @@ Next, create a method to return a Personalizer client. The parameter to the meth
 
 ## Get food items as rankable actions
 
-Actions represent the content choices you want Personalizer to rank. Add the following methods to the Program class to represent the set of actions to rank.
+Actions represent the content choices from which you want Personalizer to select the best content item. Add the following methods to the Program class to represent the set of actions and their features.
 
 [!code-csharp[Food items as actions](~/samples-personalizer/quickstarts/csharp/PersonalizerExample/Program.cs?name=createAction)]
 
 ## Get user preferences for context
 
-Add the following methods to the Program class to get a user's input from the command line for the time of day and current food preference. These will be uses as context when ranking the actions.
+Add the following methods to the Program class to get a user's input from the command line for the time of day and current food preference. These will be used as context features.
 
 [!code-csharp[Present time out day preference to the user](~/samples-personalizer/quickstarts/csharp/PersonalizerExample/Program.cs?name=createUserFeatureTimeOfDay)]
 
@@ -142,9 +124,9 @@ Both methods use the `GetKey` method to read the user's selection from the comma
 
 ## Create the learning loop
 
-The Personalizer learning loop is a cycle of rank and reward calls. In this quickstart, each rank call, to personalize the content, is followed by a reward call to tell Personalizer how well the service ranked the content.
+The Personalizer learning loop is a cycle of [Rank](#request-the-best-action) and [Reward](#send-a-reward) calls. In this quickstart, each Rank call, to personalize the content, is followed by a Reward call to tell Personalizer how well the service performed.
 
-The following code in the `main` method of the program loops through a cycle of asking the user their preferences at the command line, sending that information to Personalizer to rank, presenting the ranked selection to the customer to choose from among the list, then sending a reward to Personalizer signaling how well the service did in ranking the selection.
+The following code loops through a cycle of asking the user their preferences at the command line, sending that information to Personalizer to select the best action, presenting the selection to the customer to choose from among the list, then sending a reward score to Personalizer signaling how well the service did in its selection.
 
 [!code-csharp[Learning loop](~/samples-personalizer/quickstarts/csharp/PersonalizerExample/Program.cs?name=mainLoop)]
 
@@ -155,19 +137,19 @@ Add the following methods, which [get the content choices](#get-food-items-as-ra
 * `GetUsersTastePreference`
 * `GetKey`
 
-## Request a rank
+## Request the best action
 
-To complete the rank request, the program asks the user's preferences to create a `currentContent` of the content choices. The process can create content to exclude from the rank, shown as `excludeActions`. The rank request needs the actions, currentContext, excludeActions, and a unique rank event ID (as a GUID), to receive the ranked response.
+To complete the Rank request, the program asks the user's preferences to create a `currentContent` of the content choices. The process can create content to exclude from the actions, shown as `excludeActions`. The Rank request needs the actions and their features, currentContext features, excludeActions, and a unique event ID, to receive the response.
 
 This quickstart has simple context features of time of day and user food preference. In production systems, determining and [evaluating](../concept-feature-evaluation.md) [actions and features](../concepts-features.md) can be a non-trivial matter.
 
 [!code-csharp[The Personalizer learning loop ranks the request.](~/samples-personalizer/quickstarts/csharp/PersonalizerExample/Program.cs?name=rank)]
 
 ## Send a reward
 
-To complete the reward request, the program gets the user's selection from the command line, assigns a numeric value to each selection, then sends the unique rank event ID and the numeric value to the reward method.
+To get the reward score to send in the Reward request, the program gets the user's selection from the command line, assigns a numeric value to the selection, then sends the unique event ID and the reward score as the numeric value to the Reward API.
 
-This quickstart assigns a simple number as a reward, either a zero or a 1. In production systems, determining when and what to send to the [reward](../concept-rewards.md) call can be a non-trivial matter, depending on your specific needs.
+This quickstart assigns a simple number as a reward score, either a zero or a 1. In production systems, determining when and what to send to the [Reward](../concept-rewards.md) call can be a non-trivial matter, depending on your specific needs.
 
 [!code-csharp[The Personalizer learning loop ranks the request.](~/samples-personalizer/quickstarts/csharp/PersonalizerExample/Program.cs?name=reward)]