In the same spirit, I think API.AI also needs a good learning path.
These are the three elements which make a good learning path (in my opinion):
- The initial lessons should introduce the more basic concepts
- The future lessons should, as much as possible, build on top of the previous concepts
- At each step, there should be some kind of tangible output which reinforces the view that the learner is indeed progressing. Here, small, incremental prototypes are very handy.
That last one is pretty useful. For example, in the iconic Mythical Man Month, Fred Brooks talks about the startling morale boost from incremental development. In a similar vein, I believe that there is a lot of morale gain when users understand each step of the learning path with "working" code.
My suggested learning path
Based on the three elements I described before, this is how I believe the learning path for API.AI should be structured:
- Web hooks
- Follow up intents
I think it is quite OK to interchange steps 4 and 5, but I wouldn't change the orders from 1 to 3.
You can take a look at my step by step guide to API.AI where I follow this path.
API.AI's new and improved documentation
I got reminded of this when I saw API.AI's new documentation portal. This is what we see on the third page: (when browsing in the suggested order)
The tip inside that box is something of a sign that they are asking folks to jump into code a bit too early in the learning process.
In conclusion, while the current documentation of API.AI is probably pretty good for developers, I have some doubts as to whether it is very good for those who need those bots.