Documentation is too thin

The documentation is lacking in it’s ability to describe middleware in particular.

There is no explanation of what types of middleware you can/should pass to the bot, there is no documentation at all explaining IntentRecognitionMiddleware, or what other options there are, only a (far too slim) text that says the execution of Middleware is executed in the order that the middleware is added.

You need to detail in documentation how a user would go about setting up various ITopic classes, and how an IntentRecognitionMiddleware helps decide which topic is activated.

Consider that the developer would like to deliver the following dialog:

• Ask for the user’s name
• Ask what the user needs help with (i.e. weather or stock info)
• When user chooses stock, it will ask the user about what stock symbol to look up
• Perform the stock lookup, display it to the user in some fancy card, return to “root”

I know and understand that this is already done in part in the Alarms example, but that has so many bits and pieces to it that it is hard to understand the flow. The documentation should use some form of diagram that shows the objects involved in delivering this type of functionality, and how information flows between then - perhaps even the Alarm project would be good to use as a starting point.

Coming to V4 from V3, my questions after looking at the wiki are:

• What defines Middleware, and how does this fit in to the bot design?
• How is a typical conversation flow supposed to happen. Consider describing a multi-step dialog, such as package delivery, where the bot needs to first know the package id, and then prompt the user for a new address or a new delivery time. The samples included in .Net seem to be overly simple.
• What is the strategy for using the Intent recognizer middleware to abort one topic and pass control to a different topic?
• Is FormBuilder available?`

Having some background in V3, I can figure out some of the questions by reading code samples, but for someone starting out with v4, the complexity of writing Middleware without understanding middleware and how it is utilized by Bot is in my opinion a direct showstopper.

[JonathanFingold]

I added the following to the Overview topic on the wiki. Hopefully, this helps a little.

Under Middleware

The SDK is designed around middleware that represents application-independent components, such as:

• State managers that persist and restore state information on the context object. The SDK includes conversation and user state managers.
• Intent recognizers that analyze user messages to extrapolate the user’s intent. The SDK includes LUIS, QnA Maker, and RegEx recognizers.
• Translation middleware that can recognize the input language and translate to another language, such as one that your application understands.

[digitaldias]

Thanks for an extensive answer, Gary. Yeah, you’re right in that I was thinking about FormFlow in v3, where FormBuilder is one of the actors.

One knee-jerk reaction to naming: The term “Middleware” seems to cover a huge set of bot functionality; from topics of conversations to intent recognizers and prompts. The term itself says nothing about the responsabilities of the classes involved. Documenting what makes a piece of Middleware, and how the flow runs through it, would be essencial in having the developers understand and expand on that knowledge.