Documentation is too thin

[digitaldias]

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.

[garypretty]

@digitaldias I can't answer all of these questions, but I think I can help on a few :)

• Firstly, I agree and I am sure the team do as well that the documentation right now is thin on the ground in many places. SDK docs are currently slated for M3 in April according to the roadmap with docs being finalised in M4 in May. Right now things are moving very fast so it probably isn't that feasible to keep the docs completely up to speed until a few things are a little more nailed down over the next few weeks.

• On the specific topic of middleware there are a number of discussions happening right now which will affect the longer-term. Paying specific attention to the IntentRecognitionMiddleware, for example, this currently updates the BotContext with the TopIntent, but there is a desire to remove things like this from the BotContext and have them handled in a different way - again this is a moving picture, but one that should become clearer soon.

• You are not alone in feeling the AlarmBot sample was a little complicated - my understanding is that a simpler version of this is in the works - some work towards this has been done and the PR and the associated discussion can be seen here

• On the subject of traditional dialog examples / flows, similar to v3, the plan right now is to have this sort of pattern implemented using middleware. As far as I know there is work underway to deliver some example dialog middleware soon (within the current milestone), but this will likely be placed into some sort of separate 'toybox' repo where other example patterns can be placed.

• FormBuilder (I am going to assume you are talking about the FormFlow functionality from v3 - let me know if I am wrong) is not included right now and, again, feels like something that would be handled by some form of custom middleware at some point. I don't know this for a fact though and the team might correct me.

Ultimately I think over the comings weeks we will likely see the pieces falling into place and a little more stability in the core SDK which will then allow for more detailed documentation / wiki pages to be produced, once these are not likely to change (potentially daily at the moment!). My understanding is that the overall direction of travel for v4 is to provide a core set of capabilities for bot development, but to be less prescriptive around the patterns used to form the conversations itself (e.g. dialogs). Coming from v3 this can feel initially like a step backwards (at the moment), but in the end should allow greater flexibility and for better bot development patterns and practices to grow with the community.

Hope that helps. I am cc'ing @cleemullins in case he wants to correct me on or expand on any points. Hopefully I am not too far off though.

[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.

[garypretty]

@digitaldias I totally agree! I am sure @cleemullins and the team will appreciate the insight.

[cleemullins]

@digitalias, I agree on all fronts.

As @garypretty has pointed out, we've got a docs team churning full time. The issue is that things have not yet settled out, so they're chasing a moving target. To help with that, we added docs into the roadmap and just haven't gotten there yet.

Many of the issues you see being posted are actually from members of our docs team, as they try to figure things out, hit "weird" areas, and otherwise are trying to document this SDK.

(As for Middleware, I also agree. I know @johnataylor also strongly agrees. We're starting to put boundaries around it, define when/how it should be used, and generally providing meaningful guidance around the Middelware. I would NOT say we have achieved this yet.)

[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.

[JonathanFingold]

Closing. @digitaldias , please reopen if this issue hasn't been addressed appropriately.