Documentation updates

README.md

@@ -1,19 +1,16 @@
-# ![Conversational AI Solutions](./docs/media/conversationalai_solutions_header.png)
+![Conversational AI Solutions](./docs/media/conversationalai_solutions_header.png)
 
 This repository is the home for a set of templates and solutions to help build conversational experiences using [Azure Bot Service](https://aka.ms/azurebotservice) and [Bot Framework](https://botframework.com).
 
-## Templates
+  | Name | Description | Link 
+|------------|------------| -------------| :-----------:
+<img src="/docs/media/vatemplateintrocard.png" width="1250">| **Virtual Assistant** | Customers and partners have a significant need to deliver a conversational assistant tailored to their brand, personalized to their users, and made available across a broad range of canvases and devices. <br/><br/> Continuing Microsoft's open-sourced approach towards the Bot Framework SDK, the open-source Virtual Assistant solution provides you with a set of core foundational capabilities and full control over the end user experience. <br></br> This template incorporates the previous Enterprise Template and brings together all of the best practices and supporting components identified through building conversational experiences and greatly simplifies the creation of a new bot project including: basic conversational intents, Dispatch integration, QnA Maker, Application Insights and an automated deployment.| [Get Started](./docs/virtual-assistant/README.md)
+<img src="/docs/media/calendarskillcardexample.png" width="1250">|**Skills**|A Skill is like a standard conversational bot but with the ability to be plugged in to a broader solution. This can be a complex Virtual Assistant or perhaps an Enterprise Bot seeking to stitch together multiple bots within an organization.<br/><br/>A library of re-usable conversational skill building-blocks covering conversational use-cases enabling you to add extensive functionality to a Bot within minutes. Skills include LUIS models, Dialogs and Integration code and delivered in source code form enabling you to customise and extend as required. At this time we provide Calendar, Email, ToDo, Point of Interest skills and a number of other experimental skills. | [Get Started](./docs/skills/README.md)
+<img src="/docs/media/powerbi-conversationanalytics-alldialogsoverview.png" width="1250">|**Analytics**| Gain key insights into your bot’s health and behavior with the Conversational AI Analytics solutions. Review available telemetry, sample Application Insights queries, and Power BI dashboards to understand the full breadth of your bot’s conversations with users. | [Get Started](./docs/analytics/README.md)
 
-Name | Description | Link
------------- | ------------- | :-----------:
-Enterprise Template | A high quality conversational experience requires a foundational set of capabilities to maintain consistent quality. Install the Enterprise Bot Template for help in building a great experience with your users. <br /> <br />This template brings together all of the best practices and supporting components identified through building conversational experiences and greatly simplifies the creation of a new bot project including: basic conversational intents, Dispatch integration, QnA Maker, Application Insights and an automated deployment.| [Get Started](./templates/Enterprise-Template/README.md)
+## Need Help?
 
-## Solutions
-
-Name | Description | Link 
------------- | ------------- | :-----------:
-Virtual Assistant | Customers and partners have a significant need to deliver a conversational assistant tailored to their brand, personalized to their users, and made available across a broad range of canvases and devices. <br/><br/> Continuing Microsoft's open-sourced approach towards the Bot Framework SDK, the open-source Virtual Assistant solution provides you with a set of core foundational capabilities and full control over the end user experience.| [Get Started](./docs/virtual-assistant/README.md)
-Analytics | Gain key insights into your bot’s health and behavior with the Conversational AI Analytics solutions. Review available telemetry, sample Application Insights queries, and Power BI dashboards to understand the full breadth of your bot’s conversations with users. | [Get Started](./docs/analytics/README.md)
+If you have any questions please start with [Stack Overflow](https://stackoverflow.com/questions/tagged/botframework) where we're happy to help. Please use this GitHub Repos issue tracking capability to raise [issues](https://github.com/Microsoft/AI/issues/new?assignees=&labels=Type%3A+Bug&template=bug_report.md&title=) or [feature requests](https://github.com/Microsoft/AI/issues/new?assignees=&labels=Type%3A+Suggestion&template=feature_request.md&title=).
 
 ## Contributing
 

docs/skills/README.md

@@ -2,15 +2,31 @@
 
 # Skills Overview
 
+Skills are re-usable conversational skill building-blocks covering conversational use-cases enabling you to add extensive functionality to a Bot within minutes. Skills include LUIS models, Dialogs and Integration code and delivered in source code form enabling you to customise and extend as required. At this time we provide Calendar, Email, ToDo, Point of Interest skills and a number of other experimental skills.
+
 A Skill is like a standard conversational bot but with the ability to be plugged in to a broader solution. This can be a complex Virtual Assistant or perhaps an Enterprise Bot seeking to stitch together multiple bots within an organization.
 
 Apart from some minor differences that enable this special invocation pattern, a Skill looks and behaves like a regular bot. The same protocol is maintained between two bots to ensure a consistent approach. Skills for common scenarios like productivity and navigation to be used as-is or customized however a customer prefers.
 
+>The Skill implementations currently provided are in C# only but the remote invocation nature of the Skills does enable you to invoke C# based Skills from a typescript Bot project.
+
 ## Table of Contents
 - [Skills Overview](#skills-overview)
   - [Table of Contents](#table-of-contents)
-  - [Skills Documentation](#skills-documentation)
   - [Available Skills](#available-skills)
+  - [Skills Documentation](#skills-documentation)
+  - [Need Help?](#need-help)
+
+## Available Skills
+
+The following Skills are available out of the box, each of the documentation links below has the deployment steps required to deploy and configure Skills for your use.
+
+- [Productivity - Calendar](./productivity-calendar.md)
+- [Productivity - Email](./productivity-email.md)
+- [Productivity - To Do](./productivity-todo.md)
+- [Point of Interest](./pointofinterest.md)
+- [Automotive](./automotive.md)
+- [Experimental Skills](./experimental-skills.md)
 
 ## Skills Documentation
 The documentation outline for the preview Conversational AI Skills capability is shown below. C# and Typescript programming languages are supported.
@@ -34,13 +50,8 @@ The documentation outline for the preview Conversational AI Skills capability is
 
 :runner: is work in progress
 
-## Available Skills
 
-The following Skills are available out of the box, each of the documentation links below has the deployment steps required to deploy and configure Skills for your use.
 
-- [Productivity - Calendar](./productivity-calendar.md)
-- [Productivity - Email](./productivity-email.md)
-- [Productivity - To Do](./productivity-todo.md)
-- [Point of Interest](./pointofinterest.md)
-- [Automotive](./automotive.md)
-- [Experimental Skills](./experimental-skills.md)
+## Need Help?
+
+If you have any questions please start with [Stack Overflow](https://stackoverflow.com/questions/tagged/botframework) where we're happy to help. Please use this GitHub Repos issue tracking capability to raise [issues](https://github.com/Microsoft/AI/issues/new?assignees=&labels=Type%3A+Bug&template=bug_report.md&title=) or [feature requests](https://github.com/Microsoft/AI/issues/new?assignees=&labels=Type%3A+Suggestion&template=feature_request.md&title=).

docs/skills/csharp/gettingstarted.md

@@ -63,6 +63,8 @@ The Virtual Assistant require the following dependencies for end to end operatio
 
 To deploy your services using the default configuration, follow the steps in this common [deployment documentation page](/docs/virtual-assistant/common/deploymentsteps.md)
 
+> Note that if you choose to deploy your Skill manually or re-use an existing App-Service please ensure that Web Sockets are enabled on the App Service configuration pane. The deployment scripts supplied as part of the Skill template will do this automatically.
+
 ## Update Manifest
 
 Your newly created Skill has a basic Skill manifest file provided in the root directory (`manifestTemplate.json`), this has been pre-populated with the Skill ID and name and a sample action which you can modify at this stage if required.

docs/skills/typescript/gettingstarted.md

@@ -70,6 +70,8 @@ The Virtual Assistant require the following dependencies for end to end operatio
 
 To deploy your services using the default configuration, follow the steps in this common [deployment documentation page](/docs/virtual-assistant/common/deploymentsteps.md)
 
+> Note that if you choose to deploy your Skill manually or re-use an existing App-Service please ensure that Web Sockets are enabled on the App Service configuration pane. The deployment scripts supplied as part of the Skill template will do this automatically.
+
 ## Update Manifest
 
 Your newly created Skill has a basic Skill manifest file provided in the root directory (`manifestTemplate.json`), this has been pre-populated with the Skill ID and name and a sample action which you can modify at this stage if required.

docs/virtual-assistant/README.md

@@ -54,6 +54,10 @@ The documentation outline for the preview Conversational AI Skills capability is
 
 :runner: is work in progress
 
+## Need Help?
+
+If you have any questions please start with [Stack Overflow](https://stackoverflow.com/questions/tagged/botframework) where we're happy to help. Please use this GitHub Repos issue tracking capability to raise [issues](https://github.com/Microsoft/AI/issues/new?assignees=&labels=Type%3A+Bug&template=bug_report.md&title=) or [feature requests](https://github.com/Microsoft/AI/issues/new?assignees=&labels=Type%3A+Suggestion&template=feature_request.md&title=).
+
 # Contributing
 This project welcomes contributions and suggestions.  Most contributions require you to agree to a
 Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us

docs/virtual-assistant/common/deploymentsteps.md

@@ -1,4 +1,8 @@
-## Deployment Steps
+# Virtual Assistant and Skill Template Deployment
+
+## Deployment Steps 
+
+> Applies to Virtual Assistant Template and Skill Template (C# and Typescript variants)
 
 1. In **PowerShell Core** (pwsh.exe), change to the project directory.
 1. Run the following command:
@@ -20,4 +24,10 @@
 
 > There is a known issue with some users whereby you might experience the following error when running deployment `Could not provision Microsoft App Registration automatically. Please provide the -appId and -appPassword arguments for an existing app and try again`. In this situation, please create your own [Azure Active Directory App](https://ms.portal.azure.com/#blade/Microsoft_AAD_IAM/ActiveDirectoryMenuBlade/Overview) and manually create a new application retrieving the ApplicationID and Password/Secret. Run the above deployment script again but provide two new arguments `appId` and `appPassword` passing the values you've just retrieved.
 
-> NOTE: Take special care when providing the appSecret step above as special characters (e.g. @) can cause parse issues. Ensure you wrap these parameters in single quotes.
+> NOTE: Take special care when providing the appSecret step above as special characters (e.g. @) can cause parse issues. Ensure you wrap these parameters in single quotes.
+
+## Customising deployment using the parameters file
+
+## Creating your own ARM template
+
+We have provided a comprehensive ARM template to deploy all required capabilities which can be customised through the parameters file detailed in the previous section. If however you want to make more substantial changes - such as re-using existing deployed services please refer to the [Azure Resource Manager template documentation](https://docs.microsoft.com/en-us/azure/azure-resource-manager/resource-group-authoring-templates) for guidance and you can refer to our template for reference.

docs/virtual-assistant/csharp/gettingstarted.md

@@ -55,7 +55,6 @@ The Virtual Assistant require the following dependencies for end to end operatio
 - Azure CosmosDb (State)
 - Azure Cognitive Services - Language Understanding
 - Azure Cognitive Services - QnAMaker (including Azure Search, Azure Web App)
-- Azure Cognitive Services - Content Moderator (optional manual step)
 
 > Review the pricing and terms for the services and adjust to suit your scenario.
 

docs/virtual-assistant/typescript/gettingstarted.md

@@ -8,6 +8,10 @@
   - [Table of Contents](#table-of-contents)
   - [Prerequisites](#prerequisites)
   - [Create your project](#create-your-project)
+    - [Generate the assistant using prompts](#generate-the-assistant-using-prompts)
+    - [Generate the sample using CLI parameters](#generate-the-sample-using-cli-parameters)
+      - [Example](#example)
+  - [Deployment](#deployment)
   - [Testing](#testing)
 
 ## Prerequisites
@@ -33,14 +37,78 @@
 
 ## Create your project
 
+>//Temporary ahead of package publishing>
+
+- Clone the https://github.com/Microsoft/AI repo
+- Go to templates\Virtual-Assistant-Template\typescript\generator-botbuilder-assistant folder in a command line
+- Run npm link to symlink the package folder
+>//
+
 Now you can execute the Virtual Assistant generator with this command.
 
 ```bash
-yo botbuilder-enterprise
+yo botbuilder-assistant
 ```
 
+**At this point you have two different options to proceed:
+
+### Generate the assistant using prompts
+
+- The generator will start prompting for some information that is needed for generating the sample:
+    - `What's the name of your assistant? (customAssistant)`
+        > The name of your assistant (used also as your project's name and for the root folder's name).
+    - `What will your assistant do? ()`
+        > The description of your assistant.
+    - `Which languages will your assistant use? (by default takes all the languages)`
+        - [x] Chinese (`zh`)
+        - [x] Deutsch (`de`)
+        - [x] English (`en`)
+        - [x] French (`fr`)
+        - [x] Italian (`it`)
+        - [x] Spanish (`es`)
+    - `Do you want to change the new assistant's location?`
+        > A confirmation to change the destination for the generation.
+        - `Where do you want to generate the assistant? (by default takes the path where you are running the generator)`
+            > The destination path for the generation.
+    - `Looking good. Shall I go ahead and create your new assistant?`
+        > Final confirmation for creating the desired assistant.
+
+### Generate the sample using CLI parameters
+
+| Option                            | Description                                                                                                  |
+|-----------------------------------|--------------------------------------------------------------------------------------------------------------|
+| -n, --assistantName <name>              | name of new assistant (by default takes `customAssistant`)                                                          |
+| -d, --assistantDesc <description>       | description of the new assistant (by default takes ``) |
+| -l, --assistantLang <array of languages>| languages for the new assistant. Possible values are `de`, `en`, `es`, `fr`, `it`, `zh` (by default takes all the languages)| 
+| -p, --assistantGenerationPath <path>    | destination path for the new assistant (by default takes the path where you are runnning the generator)            |
+| --noPrompt                        | indicates to avoid the prompts                                                                               |
+
+**NOTE:** If you don't use the _--noPrompt_ option, the process will keep prompting, but using the input values by default.
+
+#### Example
+
+```bash
+> yo botbuilder-assistant -n "Virtual Assistant" -d "A description for my new assistant" -l "en,es" -p "\aPath" --noPrompt
+```
+
+After this, you can check the summary in your screen:
+```bash
+- Name: <aName>
+- Description: <aDescription>
+- Selected languages: <languages>
+- Path: <aPath>
+```
+
+>**WARNING:** The process will fail if it finds another folder with the same name of the new assistant.
+
+>**NOTE:** Remind to have an **unique** assistant's name for deployment steps. 
+
+>**NOTE:** After generating your sample, you can check its README for more information on how to deploy and test it. You can find it in the root folder of your newly created sample or [here](https://github.com/Microsoft/AI/blob/master/docs/virtual-assistant/src/typescript/gettingstarted.md).
+
 You now have your own Assistant! Follow the Deployment steps below before you try and run the project as deployment creates key dependencies required for operation.
 
+## Deployment
+
 The Virtual Assistant require the following dependencies for end to end operation which are created through an ARM script which you can modify as required.
 
 - Azure Web App
@@ -49,15 +117,14 @@ The Virtual Assistant require the following dependencies for end to end operatio
 - Azure CosmosDb (State)
 - Azure Cognitive Services - Language Understanding
 - Azure Cognitive Services - QnAMaker (including Azure Search, Azure Web App)
-- Azure Cognitive Services - Content Moderator (optional manual step)
 
 > Review the pricing and terms for the services and adjust to suit your scenario.
 
 To deploy your services using the default configuration, follow the steps in this common [deployment documentation page](/docs/virtual-assistant/common/deploymentsteps.md)
 
 ## Testing
 Once deployment is complete, you can start debugging through the following steps:
-- Start a Debugging session within Visual Studio for the Virtual Assistant project
+- Run `npm start` within the folder of your newly created assistant
 - Open the [Bot Framework Emulator](https://github.com/Microsoft/BotFramework-Emulator). 
 - Within the Emulator, choose Open Bot from the File menu:
   - Provide the endpoint of your running Bot, e.g: `http://localhost:3978/api/messages`