Documentation update for Ignite 2019 (microsoft#1458)

kevmcdonk · Nov 1, 2019 · 4622612 · 4622612
1 parent c3955a4
commit 4622612
Show file tree

Hide file tree

Showing 315 changed files with 3,667 additions and 20 deletions.
diff --git a/README.md b/README.md
@@ -1,4 +1,4 @@
-# ![Microsoft Bot Framework Composer](./docs/Assets/gh-banner.png)
+# ![Microsoft Bot Framework Composer](./docs/media/gh-banner.png)
 
 # Microsoft Bot Framework Composer [PREVIEW]
 
@@ -16,25 +16,7 @@ Bot Framework Composer is an integrated development tool for developers and mult
 Bot Framework Composer, an open source tool, enables teams working to create bots to build all kinds of conversational experiences that use the latest features from the [Bot Framework SDK](https://github.com/microsoft/botframework). The Composer app reads and writes from the [Adaptive Dialog](https://github.com/microsoft/BotBuilder-Samples/tree/master/experimental/adaptive-dialog) format, a [declarative](https://github.com/microsoft/BotBuilder-Samples/tree/master/experimental/adaptive-dialog/declarative) JSON specification shared by many tools provided by the Bot Framework. Dialogs, NLU training data and message templates are treated like normal developer assets - files that can be committed to source control and deployed alongside code updates. 
 
 ## Get Started
-
-- To get your self familiar with the Composer, read [Introduction to Bot Framework Composer](https://github.com/microsoft/BotFramework-Composer/blob/master/docs/introduction_to_bfd.md#introduction-to-bot-framework-composer).
-- To get started [deploy Bot Framework Composer](./docs/Deploying-Composer.md) on your local machine, [create your first bot](./docs/Create-Your-First-bot.md) and review the various [samples](./docs/samples.md).
-
-
-## Documentation
-* [Introduction to Bot Framework Composer](./docs/introduction_to_bfd.md)
-* [Deploying Bot Framework Composer](./docs/Deploying-Composer.md)
-* [Create your first bot using Composer](./docs/Create-Your-First-Bot.md) 
-* [Triggers and Events](./docs/triggers_and_events.md)
-* [Using Memory](./docs/using_memory.md)
-* [Controlling Conversation Flow](./docs/controlling_conversation_flow.md)
-* [Testing and Debugging](./docs/testing_debugging.md)
-* [Learning from samples](./docs/samples.md)
-* [All About Interruption](./docs/all_about_interruption.md)
-
-> Additional documentation for Composer [can be found here](./docs/README.md).
-
-
+To learn about the Bot Framework Composer, read the [documentation](toc.md).
 
 ## Contributing
 

diff --git a/docs/bfcomposer-intro.md b/docs/bfcomposer-intro.md
@@ -0,0 +1,64 @@
+# Introduction to Bot Framework Composer
+Bot Framework Composer is an integrated development tool for developers and multi-disciplinary teams to build bots and other types of conversational software with the Microsoft Bot Framework. Composer enables teams to create bots that use the latest features from the Bot Framework SDK.
+
+![BF Composer](./media/introduction/composer-overview.png)
+
+ Within this tool, you'll find everything you need to build a sophisticated conversational experience:
+* A visual dialog editor 
+* Tools to train and manage a language understanding component
+* A powerful language generation and templating system
+* A ready-to-use bot runtime executable 
+
+## Advantage of developing bots with Composer
+Developers familiar with the Bot Framework SDK will notice differences between bots developed with it and the Bot Framwork Composer. Below are some of the advantages of developing bots in Composer:
+- Adaptive dialogs allow for Language Generation (LG), which can simplify interruption handling and give bots character
+- The visual representation and editing in Composer eliminates the need for boilerplate code and makes bot development more accessible
+- No longer need to navigate between experiences to maintain LU model as it is editable within the app
+- Time saved with fewer steps to set up your environment and start bots
+
+A major difference between the current version of the Bot Framework SDK and Composer is that the apps created using Composer uses the Adaptive dialog format, a JSON specification shared by many tools provided by the Bot Framework. You can find more information about Adaptive dialog [here](https://github.com/microsoft/BotBuilder-Samples/tree/master/experimental/adaptive-dialog).
+
+You can manage Composer assests, such as Dialogs, LU training data, and message templates like normal developer assets - files that can be committed to source control and deployed alongside code updates.
+
+## Language Understanding (LU)
+
+Language Understanding is a core component of Composer, allowing developers and conversation designers to train language understanding directly in the context of editing a dialog.  
+
+As dialogs are edited in Composer developers can continuously add to their bot's natural language capabilities through a simple markdown-like format that makes it easy to define new intents and provide sample utterances.
+
+![BF Composer NLU](./media/introduction/intro-nlu.png)
+
+ Composer detects changes and updates the bot's cloud-based NLU model automatically so it is always up to date.
+
+## Language Generation (LG)
+
+Creating grammatically correct, data-driven responses that also use a consistent tone and convey a clear brand voice has always been a challenge for bot developers. Composer's integrated [Language Generation](https://github.com/microsoft/BotBuilder-Samples/tree/master/experimental/language-generation) system allows developers, and the writers who work with them, to create replies with a great deal of flexibility.
+
+![BF Composer LG](.//media/language_generation/bot_responses.png)
+
+With Language Generation (LG), previously complex tasks can be quickly achieved:
+* Include dynamic elements in messages
+* Generate grammatically correct lists, pronouns, articles
+* Provide context-sensitive variation in messages
+* Create Adaptive Cards attachments, as seen above
+
+
+## Unified toolset
+
+Under the hood, Composer harnesses the power of many of the components from the Bot Framework SDK. When building bots in Composer, developers will have access to:
+
+* [Adaptive dialogs](https://github.com/microsoft/BotBuilder-Samples/tree/master/experimental/adaptive-dialog) and the [Bot Framework SDK](https://github.com/microsoft/botframework-sdk)
+* Language Understanding service from [LUIS](https://www.luis.ai/home)
+* Built-in [Language Generation](https://github.com/microsoft/BotBuilder-Samples/tree/master/experimental/language-generation) and [expression library](https://github.com/microsoft/BotBuilder-Samples/tree/master/experimental/common-expression-language)
+* [QnA Maker](https://www.qnamaker.ai/) capabilities
+* [Bot Framework Emulator](https://github.com/microsoft/BotFramework-Emulator)
+
+After creating bots with Composer the resulting bot project will contain reusable assets in the form of JSON and Markdown files that can be bundled and packaged with a bot's source code. These files can be used with a wide variety of compatible tools from the Bot Framework.
+
+## Further reading
+
+* [Bot Framework on Github](https://github.com/microsoft/botframework)
+
+## Next
+
+* Learn how to [create an echo bot](./tutorial-create-echobot.md) using Composer
diff --git a/docs/concept-dialog.md b/docs/concept-dialog.md
@@ -0,0 +1,122 @@
+# Dialogs 
+
+In Bot Framework Composer, dialogs are functional components offered in a visual interface and do not require you to write code. The dialog system supports building a pluggable and extensible model that integrates building blocks of bot functionality. Dialogs help users focus on conversation modeling rather than the mechanics of dialog management.
+
+>[!NOTE]
+> The dialog system in Composer is based on [Adaptive dialogs](https://github.com/Microsoft/BotBuilder-Samples/tree/master/experimental/adaptive-dialog#readme). 
+ 
+## Types of dialogs  
+There are two types of dialogs in Composer: 
+- main dialog
+- child dialog
+
+You create a dialog in Composer to manage a conversation objective. Main dialog is initialized by default when you create a new bot and it has a **.Main** file extension. Each bot has one main dialog but can have multiple child dialogs or no child dialog. Please read [this section](https://github.com/microsoft/BotFramework-Composer/blob/kaiqb/Ignite2019/docs/concept-dialog.md#create-a-dialog) about how to create a dialog in Composer. 
+
+At runtime, the main dialog is called into action and becomes the active dialog, triggering event handlers with pre-defined actions. As the conversation flows, a child dialog can be called by a main dialog, and vice versa. Different child dialogs can be called with each other as well. 
+
+## Anatomy of a dialog 
+A dialog contains a set of event handlers (triggers) to handle different events. Currently, Composer provides five different types of event handlers in a dialog: `Handle an Intent`, `Handle Unknown Intent`, `Handle a Dialog Event`, `Handle an Event: Activity`, and `Handle a Custom Event`.  
+
+Most dialogs contain an event handler configured to respond to the `BeginDialog` event. Inside the `BeginDialog` event are actions that should execute immediately every time the dialog starts. For more information, please read [events and triggers](https://github.com/microsoft/BotFramework-Composer/blob/kaiqb/Ignite2019/docs/concept-events-and-triggers.md) article.
+
+![event handlers](./media/dialog/eventhandlers.png)
+
+Usually when a dialog is called into action, its **recognizer** will start to process the message and try to extract the primary **intent** and any **entity values** the message includes. After processing the message, both the **intent** and **entity values** are passed onto the dialog's event handlers. Composer currently supports two types of recognizers: LUIS recognizer (default) and Regular expression recognizer. You can _only_ choose one type of recognizer for each dialog. A dialog can have no recognizer. 
+
+![recognizer](./media/dialog/recognizer.png)
+
+> [!NOTE]
+> **Recognizers** provide the functionality of understanding and extracting meaningful pieces of information from a user's input. All recognizers emit events when the recognizer picks up an intent (or extracts entities) from a given user utterance. **Recognizer** of a dialog is not always called into play when a dialog is called. It is a matter of how you design and model your dialog system.   
+
+Event handlers contain a series of actions that the bot will undertake to fulfill a user's request. Composer offers a wide range of action components such as `Send a response` for sending text messages and `Ask a Question` for prompts / asking questions. Users can also add branches and loops when designing their dialog system using the `Create a condition` action, or use `Manage properties` for setting properties and memory use in a [conversation flow](https://github.com/microsoft/BotFramework-Composer/blob/kaiqb/Ignite2019/docs/concept-memory.md). 
+
+![actions](./media/dialog/actions.png)
+
+As the bot takes actions and sends messages, the **language generator** is called into play. It generates messages from variables and templates and sends them back to the user. Language generators can be used to create reusable components, variable messages, and dynamic messages that are grammatically correct. The following [diagram](https://github.com/microsoft/BotBuilder-Samples/blob/master/experimental/adaptive-dialog/docs/Assets/adaptive-dialog-anatomy.png) shows the anatomy of a dialog in Composer. Please note that dialogs in Composer are based on [Adaptive dialogs](https://github.com/Microsoft/BotBuilder-Samples/tree/master/experimental/adaptive-dialog#readme). 
+
+![adaptive-dialog-anatomy](./media/dialog/adaptive-dialog-anatomy.png)
+
+## Create a dialog 
+
+When you create a bot in Composer you also create its main dialog by default. To create a bot project, please follow the steps:
+
+1. On the left side of the Composer home screen, click `+ New` from the upper left corner (or the big `+ ` sign under Bot Framework Composer description). After you see the pop-up window, select "Create from scratch" and click `Submit`. 
+
+![create_new_bot](./media/dialog/create_new_bot.png) 
+
+2. On the pop-up window give a name for your bot then fill in brief description and click `Next`. You can leave the `Location` field as is at this time. 
+
+![define_new_bot](./media/dialog/define_new_bot.png)
+
+When your bot is created successfully you will see a **.Main** dialog in the dialog navigation pane. Congratulations! You have created your first bot and its main dialog using Composer. Below is a screenshot of a bot named `MyBot` and its main dialog named `MyBot.Main`: 
+
+![main_dialog](./media/dialog/main_dialog.png)
+
+> [!NOTE]
+> As you may notice, after you create a bot a `Handle ConversationUpdate` trigger will be created by default as well. It is a trigger to handle activities such as sending a welcome message. For details please read the [events and triggers](https://github.com/microsoft/BotFramework-Composer/blob/kaiqb/Ignite2019/docs/concept-events-and-triggers-draft.md) article and how to [define triggers](https://github.com/microsoft/BotFramework-Composer/blob/kaiqb/Ignite2019/docs/howto-defining-triggers.md) article. 
+
+## Add a dialog 
+
+After you create a bot you are also creating its main dialog by default. The main dialog is like the brain of our bot, controlling and managing the dialog system. Sometimes we find it useful to create a child dialog that contains a chunk of functionality so that our dialog system is organized and easily managed. Let's walk through a very simple example to show how to create a child dialog and wire it up with the main dialog. 
+
+1. Create a new dialog. Click `New Dialog` on the navigation pane. On the pop-up window give a name for the new dialog and optionally fill in the description and then click `Next`. 
+
+![weather_dialog](./media/dialog/weather_dialog.png)
+
+After that, you will see an empty dialog you created on the navigation pane. When creating a child dialog you also create a `Handle an Event: BeginDialog` trigger by default. The new dialog named `Weather` may look like this: 
+
+![new_dialog](./media/dialog/new_dialog.png)
+
+2. Define an action in the `BeginDialog` trigger. Click the `+` sign under `Handle an Event: BeginDialog` in the new dialog and select `Send a response`. In the language generation editor put a sentence: "The weather dialog is called with success!"
+
+![send_response](./media/dialog/send_response.gif)
+
+3. Wire up the new dialog. Click the main dialog in navigation pane and select `Handle ConversationUpdate`. In the authoring canvas, click the "+" sign under `Handle ConversationUpdate` and select `Dialog management` and then `Begin a new dialog`. `Begin a new dialog` is a dialog action that begins another dialog. When that dialog is completed, it will return to the caller. 
+
+![begin_dialog_action](./media/dialog/begin_dialog_action.png)
+
+Now in the property editor on the right side select the dialog you want to wire up from the drop-down menu. Let's select `Weather` dialog and then you will see the name of the new dialog appear in the `Begin a new dialog` action node. 
+
+![wire_up_dialog](./media/dialog/wire_up_dialog.gif)
+
+When the bot runs, the pattern of this simple design is as follows: 
+
+- The main dialog `MyBot.Main` is called at bot runtime.
+- The `Handle ConversationUpdate` trigger in the main dialog is activated and begins to execute the `Begin a new dialog` action which begins `Weather` dialog. 
+- When `Weather` dialog becomes active, `Handle ConversationUpdate` in the child dialog is triggered and send the response "The weather dialog is called with success!" to users. 
+
+You can test the result by clicking the `Start` button on the upper corner and then click `Test in Emulator`. You should be able to see the following result in the emulator: 
+
+![test_emulator](./media/dialog/test_emulator.png)
+
+## Dialog actions 
+
+A bot will have a few dialogs or hundreds of individual dialogs and traditionally it's difficult to manage the dialog system and the conversation with user. In the previous "Add a dialog" section, we cover how to create a child dialog and wire it up to the dialog system using `Begin a new dialog`. In fact, Composer provides more dialog actions to make it easier to manage our dialog system. 
+
+You can access the different dialog actions by clicking the "+" node after a trigger and then select `Dialog management`.  
+
+![dialog_action](./media/dialog/dialog_action.png)
+
+<!-- We might need a how-to article documenting how to use each type of the dialog actions.  -->
+
+Below is a list of the dialog actions provided in Composer: 
+
+
+| Dialog Action        | Description                                                                                                                      |
+| -------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
+| Begin a new dialog       | An action that begins another dialog. When that dialog is completed, it will return to the caller.                                 |
+| End this dialog           | A command that ends the current dialog, returning the `resultProperty` as the result of the dialog.    |
+| Cancel all dialogs   | A command to cancel all of the current dialogs by emitting an event that must be caught to prevent cancelation from propagating |
+| End this turn      | A command to end the current turn without ending the dialog.                                                                     |
+| Repeat this Dialog   | An action that repeats the current dialog with the same dialog.                                                                 |
+| Replace this Dialog  | An action that replaces the current dialog with the target dialog.                                                                      |
+
+With these dialog actions, we can easily build a pluggable and extensible dialog system without worrying about the mechanics of dialog management. 
+
+## References 
+[Dialogs library](https://docs.microsoft.com/en-us/azure/bot-service/bot-builder-concept-dialog?view=azure-bot-service-4.0)
+
+[Adaptive dialogs](https://github.com/Microsoft/BotBuilder-Samples/tree/master/experimental/adaptive-dialog#readme)
+
+## Next 
+[Events and triggers](https://github.com/microsoft/BotFramework-Composer/blob/kaiqb/Ignite2019/docs/concept-events-and-triggers.md)