Tzanko has already added a basic description of the system to the ipython manual. For the long run, I think we should consider making the help system be a set of notebooks itself.
This way users could see the capabilities of the system by executing and modifying said notebooks. If we can get this to work well, it opens the door for all sorts of notebooks as a mechanism for distributing python-based tutorials in many fields.
Should we run the help against a separate kernel? This has pros and cons:
- It shields the user from side-effects induced by executing the help code in his own namespace.
- But the presence of two kernels may confuse some users.
In the end, I still think it's better to have a separate kernel for the help. Users can always reopen a help file in their own notebook, or copy/paste code, if they want it absorbed. This can be well explained to avoid confusion, but in the long run I think it's technically a much cleaner solution.
