[Vm-dev] instantiateClass:indexableSize: upper limit?
tim at rowledge.org
Sat Jun 24 00:03:01 UTC 2017
Extending the help system is an excellent idea. A very good first job might be to properly condense all the items currently in the Help docking bar menu into the help browser and then get rid of those menu items.
Having everything within the help browser would have the desirable side effect of making it unnecessary to fix the odd behaviour shown if you choose Help->The Squeak User Interface (as one example) - the help browser opens on that section, which is nice, but if you should happen to click on the ‘Search Results’ list entry then your help goes away and there is no way to retrieve it (other than starting from the beginning).
A help browser is an excellent place for longer form explanations of what a part of the system does and how it does it, tying together multiple classes and code scattered around. Making sure that there are pointers to the class-specific comments (or perhaps embedding them?) within those larger help articles would be smart. Likewise having pointers from a class to any help article that discusses it would be nice. I very much like the way some help articles have executable examples with in them - full marks to whoever has provided them. Having the window menus for the main tools able to open a help browser aimed at the doc for the tool would be nice.
The most important thing about any help system is that it is actually used, so that it becomes a worthwhile habit to look in it for information. It isn’t too hard to make a tool that is easy to add information to, nor to make it easy to find stuff within. The real trick is getting everyone to remember to add well-written articles to it.
tim Rowledge; tim at rowledge.org; http://www.rowledge.org/tim
Fractured Idiom:- PORTE-KOCHERE - Sacramental wine
More information about the Vm-dev