microsoft · ryanisgrig · May 3, 2019 · May 3, 2019 · May 3, 2019
diff --git a/docs/advanced/assistant/customisingdeployment.md b/docs/advanced/assistant/customisingdeployment.md
diff --git a/docs/advanced/assistant/customizedeployment.md b/docs/advanced/assistant/customizedeployment.md
@@ -0,0 +1,67 @@
+## How To: Customize Deployment
+
+The Virtual Assistant Template relies on a number of Azure resources to run. The included deployment scripts and ARM template use the following default configurations for these services:
+
+Resource | Tier | Notes |
+-------- | ---- | ----- |
+Azure Bot Service | S1 | The Azure Bot Service resource stores configuration information that allows your Virtual Assistant to be accessed on the supported Channels and provide OAuth authentication. |
+Azure Blob Storage | Standard LRS | Used to store conversation transcripts.
+Azure Cosmos DB | Standard | Used to store conversation state. |
+Azure App Service Plan | S1 | Used to host your Bot Web App and QnA Maker Web App. |
+Azure Application Insights | N/A | Used to capture conversation and application telemetry.
+Bot Web App | N/A | Hosts your Bot application.
+Language Understanding | S0 | Subscription keys for Language Understanding Cognitive Service.
+QnA Maker | S0 | Subscription keys for QnA Maker Cognitive Service.
+QnA Maker Web App | N/A | Hosts your QnA Maker knowledgebases.
+QnA Maker Azure Search Service | Standard | Search index for your QnA Maker knowledgebases.
+Content Moderator | S0 | Subscription keys for Content Moderator Cognitive Service.
+
+Any of the following parameters in the ARM template can be overridden with your preferred values using the `parameters.template.json` file provided in the `Deployment\Resources` folder:
+- name
+- location  
+- microsoftAppId
+- microsoftAppPassword
+- cosmosDbName
+- storageAccountName
+- appServicePlanName
+- appServicePlanSku
+- appInsightsName
+- appInsightsLocation
+- botWebAppName
+- botServiceName
+- botServiceSku
+- contentModeratorName
+- contentModeratorSku
+- contentModeratorLocation
+- luisServiceName
+- luisServiceSku
+- luisServiceLocation
+- qnaMakerServiceName
+- qnaMakerServiceSku
+- qnaServiceLocation
+- qnaMakerSearchName
+- qnaMakerSearchSku
+- qnaMakerWebAppName
+
+Simply update the parameters.template.json file with your preferred values, like so:
+
+```
+{
+  "$schema": "https://schema.management.azure.com/schemas/2015-01-01/deploymentParameters.json#",
+  "contentVersion": "1.0.0.0",
+  "parameters": {
+    "appInsightsLocation": {
+      "value": "westus2"
+    },
+    "qnaMakerSearchSku": {
+      "value": "basic"
+    }
+  }
+}
+```
+
+Then provide the path to the file as an argument on the `deploy.ps1` script:
+
+```
+.\Deployment\Scripts\deploy.ps1 -parametersFile .\Deployment\Resources\parameters.template.json
+```
diff --git a/docs/readme.md b/docs/readme.md
@@ -14,7 +14,7 @@
 
 # Overview
 
-> High level overview into the Virtual Assistant, Skills and Analytics.
+> High-level overview into the Virtual Assistant, Skills and Analytics.
 
 |Name|Description|
 |-------------|-----------|
@@ -34,41 +34,33 @@
 |4. Customize your Skill <br/><br/><p align="center">[![Customize your Skill with C#](./media/csharp_icon.png)](/docs/tutorials/csharp/customizeskill.md) [![Customize your Skill with TypeScript](./media/typescript_icon.png)](/docs/tutorials/typescript/customizeassistant.md)</p>|Building your first skill| 
 
 
-# Advanced Scenarios
+# How-To
 
-> How-to guides on achieving more complex scenarios.
+> How-to guides for achieving more complex scenarios.
 
 ## Virtual Assistant
 
-|Name|Description|
-|------------|-----------|
-|[Template overview](/docs/advanced/assistant/templateoutline.md)|An outline of what the Virtual Assistant template provides| 
-|[Under the covers](/docs/advanced/assistant/underthecovers.md)|Detailed documentation covering what the template provides and how it works| 
-|[Enhance your Assistant with additional Skills](/docs/skills/common/addingskills.md)|Adding the out-of-the-box Skills to your Virtual Assistant|
-|Authenticating users to your Assistant <br/><br/><p align="center">[![Authenticating users to your Assistant with C#](./media/csharp_icon.png)](/docs/advanced/assistant/csharp/addauthentication.md) [![Authenticating users to your Assistant with TypeScript](./media/typescript_icon.png)](/docs/advanced/assistant/typescript/addauthentication.md)</p>|How to add user authentication to your Assistant|
-|[Linked Accounts](/docs/advanced/assistant/linkedaccounts.md)|Enable users to link third party accounts (e.g. Office 365) to your Assistant|
-|Migrating from the Enterprise Template <br/><br/><p align="center">[![Migrating from the Enterprise Template with C#](./media/csharp_icon.png)](/docs/advanced/assistant/csharp/ettovamigration.md)</p>|Guidance on how to move from an Enterprise Template based Bot to the new Template|
-|Migrating from the old Virtual Assistant solution <br/><br/><p align="center">[![Migrating from the beta Virtual Assistant solution with C#](./media/csharp_icon.png)](/docs/advanced/assistant/csharp/oldvatovamigration.md)</p>|Guidance on how to move from the original Virtual Assistant solution to the new Template|
-|[Messaging your users proactively](/docs/advanced/assistant/csharp/proactivemessaging.md)|Adding proactive experiences to your assistant|
-|[Enable cross bot communication into one conversational experience](/docs/advanced/assistant/parentchildbotpattern.md)|Create one central Assistant which hands-off to child bots (a common enterprise scenario)|
-|[Customize your Azure resource deployment](/docs/advanced/assistant/customisingdeployment.md)|How to customise the provided ARM template for different deployment scenarios.|
-|Secure your keys using Azure Key Vault :construction_worker_woman: |How to safeguard your keys using Azure Key Vault|
+| Name | Description |
+| ---- | ----------- |
+| [How To: Enhance your Assistant with additional Skills](/docs/skills/common/addingskills.md) | Adding the out-of-the-box Skills to your Virtual Assistant |
+| How To: Authenticate users in your Assistant <br/><br/><p align="center">[![Authenticating users to your Assistant with C#](./media/csharp_icon.png)](/docs/advanced/assistant/csharp/addauthentication.md) [![Authenticating users to your Assistant with TypeScript](./media/typescript_icon.png)](/docs/advanced/assistant/typescript/addauthentication.md)</p>|How to add user authentication to your Assistant |
+| [How To: Enable Linked Accounts](/docs/advanced/assistant/linkedaccounts.md) | Enable users to link third party accounts (e.g. Office 365) to your Assistant |
+| How To: Migrate from the Enterprise Template <br/><br/><p align="center">[![Migrating from the Enterprise Template with C#](./media/csharp_icon.png)](/docs/advanced/assistant/csharp/ettovamigration.md)</p> | Guidance on how to move from an Enterprise Template based Bot to the new Template|
+| How to: Migrate from the old Virtual Assistant solution <br/><br/><p align="center">[![Migrating from the beta Virtual Assistant solution with C#](./media/csharp_icon.png)](/docs/advanced/assistant/csharp/oldvatovamigration.md)</p>|Guidance on how to move from the original Virtual Assistant solution to the new Template |
+| [How To: Messaging your users proactively](/docs/advanced/assistant/csharp/proactivemessaging.md) | Adding proactive experiences to your assistant |
+| [How To: Enable cross bot communication into one conversational experience](/docs/advanced/assistant/parentchildbotpattern.md) | Create one central Assistant which hands-off to child bots (a common enterprise scenario) |
+| [How To: Customize Azure Resource Deployment](/docs/advanced/assistant/customizedeployment.md) | How to customise the provided ARM template for different deployment scenarios. |
+| How To: Secure your keys using Azure Key Vault :construction_worker_woman: | How to safeguard your keys using Azure Key Vault|
 
 
 ## Skills
 
-|Name|Description|
-|------------|-----------|
-|[Adding a new Skill to solution](/docs/advanced/skills/addingskills.md)| Adding a Skill|
-|[Calendar Skill](/docs/advanced/skills/productivity-calendar.md)|Add calendar capabilities to your assistant. Powered by Microsoft Graph and Google.|
-|[Email Skill](/docs/advanced/skills/productivity-email.md)|Add email capabilities to your assistant. Powered by Microsoft Graph and Google.|
-|[To-Do Skill](/docs/advanced/skills/productivity-todo.md)|Add task management capabilities to your assistant. Powered by Microsoft Graph.|
-|[Point of Interest Skill](/docs/advanced/skills/productivity-pointofinterest.md)|Find points of interest and directions. Powered by Azure Maps and FourSquare.|
-|[Automotive Skill](/docs/advanced/skills/automotive.md)|Industry-vertical Skill for showcasing enabling car feature control.|
-|[Experimental Skills](/docs/advanced/skills/experimental.md)|News, Restaurant Booking and Weather.|
-|Add Skills to an existing v4 SDK bot<br/><br/><p align="center">[![Adding Skill support to a v4 SDK Bot with C#](./media/csharp_icon.png)](/docs/advanced/skills/csharp/addskillsupportforv4bot.md) [![Adding Skill support to a v4 SDK Bot with TypeScript](./media/typescript_icon.png)](/docs/advanced/skills/typescript/addskillsupportforv4bot.md)</p>|How to add Skills to an existing bot (not Virtual Assistant template).|
-|Convert an existing v4 SDK Bot to a Skill <br/><br/><p align="center">[![Enable Skills on an existing v4 SDK Bot with C#](./media/csharp_icon.png)](/docs/advanced/skills/csharp/skillenablingav4bot.md) [![Enable Skills on an existing v4 SDK Bot with TypeScript](./media/typescript_icon.png)](/docs/advanced/skills/typescript/skillenablingav4bot.md)</p>|Steps required to take an existing and make it available as a skill.|
-|[Best practices for Skill development](/docs/advanced/skills/bestpractices.md)|Design Best practices for Skills|
+| Name | Description |
+| ---- | ----------- |
+| [How To: Add a new Skill to your Assistant](/docs/advanced/skills/addingskills.md) | Adding a Skill |
+| How To: Add Skills to an existing SDK v4 bot<br/><br/><p align="center">[![Adding Skill support to a v4 SDK Bot with C#](./media/csharp_icon.png)](/docs/advanced/skills/csharp/addskillsupportforv4bot.md) [![Adding Skill support to a v4 SDK Bot with TypeScript](./media/typescript_icon.png)](/docs/advanced/skills/typescript/addskillsupportforv4bot.md)</p>|How to add Skills to an existing bot (not Virtual Assistant template). | 
+|How To: Convert an existing v4 SDK Bot to a Skill <br/><br/><p align="center">[![Enable Skills on an existing v4 SDK Bot with C#](./media/csharp_icon.png)](/docs/advanced/skills/csharp/skillenablingav4bot.md) [![Enable Skills on an existing v4 SDK Bot with TypeScript](./media/typescript_icon.png)](/docs/advanced/skills/typescript/skillenablingav4bot.md)</p> | Steps required to take an existing and make it available as a skill. |
+| [How To: Develop a Skill](/docs/advanced/skills/bestpractices.md) | Design Best practices for Skills |
 
 # Reference 
 
@@ -78,12 +70,14 @@
 
 |Name|Description|
 |-------------|-----------|
+|[Template Outline](/docs/advanced/assistant/templateoutline.md)|An outline of what the Virtual Assistant template provides| 
+|[Under the covers](/docs/advanced/assistant/underthecovers.md)|Detailed documentation covering what the template provides and how it works| 
 |[Underlying architecture](/docs/reference/assistant/architecture.md)|Detailed exploration of the overall Virtual Assistant Architecture|
 |[Template structure](/docs/reference/assistant/projectstructure.md)|Walkthrough of your Virtual Assistant project|
 |[Generating bot responses](/docs/reference/assistant/responses.md)|Your Virtual Assistant can respond in a variety of ways depending on the scenario and the users active device or conversation canvas|
 |[Managing backend client events](/docs/reference/assistant/events.md)|Events enable custom apps or device experiences to pass device or contextual user information to an assistant behind the scenes.|
 |[Enabling speech scenarios](/docs/reference/assistant/speechenablement.md)|Ensure your Virtual Assistant and Experiences work well in Speech scenarios|
-|[Deployment script](/docs/reference/assistant/deploymentscriptapproach.md)|Walkthrough of the deployment script approach used in the Virtual Assistant|
+|[Deployment Scripts](/docs/reference/assistant/deploymentscripts) | Reference for deployment scripts provided in the Virtual Assistant Template |
 
 ## Skills
 
@@ -95,6 +89,12 @@
 |[Skill Manifest](/docs/reference/skills/skillmanifest.md)| Overview of the Skill Manifest file and it's role with Skill registration and invocation|
 |[Skill CLI Tools](/docs/reference/skills/skillcli.md)| Detailed information on the Skill command line tool and the steps it performs on your behalf.|
 |[Adaptive Card Styling](/docs/reference/skills/adaptivecardstyling.md)|Adjusting the look and feel of an Assistant's cards to reflect your brand|
+|[Calendar Skill](/docs/advanced/skills/productivity-calendar.md)|Add calendar capabilities to your assistant. Powered by Microsoft Graph and Google.|
+|[Email Skill](/docs/advanced/skills/productivity-email.md)|Add email capabilities to your assistant. Powered by Microsoft Graph and Google.|
+|[To-Do Skill](/docs/advanced/skills/productivity-todo.md)|Add task management capabilities to your assistant. Powered by Microsoft Graph.|
+|[Point of Interest Skill](/docs/advanced/skills/productivity-pointofinterest.md)|Find points of interest and directions. Powered by Azure Maps and FourSquare.|
+|[Automotive Skill](/docs/advanced/skills/automotive.md)|Industry-vertical Skill for showcasing enabling car feature control.|
+|[Experimental Skills](/docs/advanced/skills/experimental.md)|News, Restaurant Booking and Weather.|
 
 ## Analytics
 

diff --git a/docs/reference/assistant/deploymentscriptapproach.md b/docs/reference/assistant/deploymentscriptapproach.md
diff --git a/docs/reference/assistant/deploymentscripts.md b/docs/reference/assistant/deploymentscripts.md
@@ -0,0 +1,49 @@
+## Reference: PowerShell Deployment Scripts
+
+A number of PowerShell scripts are provided in the Virtual Assistant Template to help deploy and configure your different resources. Please find details on each script's purpose, parameters, and outputs below.
+
+### deploy.ps1
+This script orchestrates the deployment of all Azure Resources and Cognitive Models to get the Virtual Assistant running.
+
+#### Parameters
+| Parameter | Description | Required? |
+| --------- | ----------- | --------- |
+| name | The name for your Azure resources. | Yes |
+| location | The region for your Azure resource group and resources. | Yes |
+| appPassword | The password for your Microsoft App Registration. If `-appId` is provided this should be the password for your existing Microsoft App Registration. Otherwise, a new registration will be created using this password. | Yes |
+| luisAuthoringRegion | The region to deploy LUIS apps`| Yes |
+| luisAuthoringKey | The authoring key for the LUIS portal. Must be valid key for `-luisAuthoringRegion`. | Yes |
+| resourceGroup | The name for your Azure resource group. Default value is the name parameter. | No
+| appId | The application Id for your Microsoft App Registration. | No |
+| parametersFile | Optional configuration file for ARM Template deployment. | No |
+| languages | Specifies which languages to deploy cognitive models in a comma separated string (e.g. "en-us,de-de,es-es"). Defaults to "en-us". | No |
+| outFolder | Location to save `appsettings.json` and `cognitivemodels.json` configuration files. Defaults to current directory. | No |
+| logFile | Log file for any errors that occur during script execution. Defaults to `Deployment` folder | No |
+
+
+### deploy_cognitive_models.ps1
+This script deploys all the language models found in `Deployment\Resources\LU` and the knowledgebases found in `Deployment\Resources\QnA`. Finally it creates a Dispatch model to dispatch between all cognitive models.
+
+#### Parameters
+| Parameter | Description | Required? |
+| --------- | ----------- | --------- |
+| name | The base name for all Cognitive Models. Model language and name will be appended. (e.g MyAssistanten_General )| Yes |
+| luisAuthoringRegion | The region to deploy LUIS apps`| Yes |
+| luisAuthoringKey | The authoring key for the LUIS portal. Must be valid key for `-luisAuthoringRegion`. | Yes |
+| qnaSubscriptionKey | The subscription key for the QnA Maker service. Can be found in the Azure Portal. | Yes |
+| languages | Specifies which languages to deploy cognitive models in a comma separated string (e.g. "en-us,de-de,es-es"). Defaults to "en-us". | No |
+| outFolder | Location to save `cognitivemodels.json` configuration file. Defaults to current directory. | No |
+| logFile | Log file for any errors that occur during script execution. Defaults to `Deployment` folder | No |
+
+### update_cognitive_models.ps1
+This script updates your hosted language models and knowledgebases based on local .lu files. Or, it can update your local .lu files based on your current models. Finally, it refreshes your dispatch model with the latest changes.
+
+| Parameter | Description | Required? |
+| --------- | ----------- | --------- |
+| configFile | The folder path to the cognitivemodels.json file. Defaults to current directory. | No |
+| RemoteToLocal | Flag indicating that local files should be updated based on hosted models. Defaults to false. | No |
+| dispatchFolder | The folder path to the .dispatch file. Defaults to `Deployment\Resources\Dispatch` | No |
+| luisFolder | The folder path to the .lu files for your LUIS models. Defaults to `Deployment\Resources\LU` | No |
+| qnaFolder | The folder path to the .lu files for your QnA Maker knowledgebases. Defaults to `Deployment\Resources\QnA` | No |
+| lgOutFolder | The folder path output LuisGen file for your Dispatch model. Defaults `.\Services` | No |
+| logFile | Log file for any errors that occur during script execution. Defaults to `Deployment` folder | No |