There are also the HelpTopic classes. WebClient has some IIRC. Since the texts reside in those classes, they would be placed next to the code in the package.
Am 23.06.2017 21:03 schrieb "Juan Vuletich" JuanVuletich@zoho.com:
On 6/23/2017 2:01 PM, tim Rowledge wrote:
On 23-06-2017, at 9:45 AM, Eliot Mirandaeliot.miranda@gmail.com
wrote:
To the general audience, I think information like the above is key to
being able to understand and exploit the system effectively, but where should it reside? Clearly "in my head" is not satisfactory. It belongs somewhere in the image, but it needs to be somewhere where people can find it and/or will look. Suggestions for an "architectural information" documentation section gratefully received. Object class>>whatIsAPrimitive might perhaps work or perhaps be overloaded.
A brief explanation in the sources as a comment for the class and/or
some relevant methods *plus* a link to a swiki page with the full details. The briefest explanation might well be as little as “this is a quite complex issue; see swiki.squeak.org/85643505485"
tim
tim Rowledge; tim@rowledge.org; http://www.rowledge.org/tim Useful random insult:- A .22 caliber intellect in a .357 Magnum world.
But this information is for Smalltalk developers, not just for VM developers. And urls might eventually break.
I think the full information on how to better use the VM belong in some file in VM sources, maybe one or several .md files. And Smalltalk systems using the VMs might chose to duplicate it in the image. I'd surely do it for Cuis.
This might be too much for Object class>>whatIsAPrimitive. I think some methods in a 'documentation' category in SystemDictionary would be better. Or one (or several) new classes, just for this. Better if we can share them in all the distributions: Squeak, Pharo, Newspeak and Cuis.
Thanks,
-- Juan Vuletich www.cuis-smalltalk.org https://github.com/Cuis-Smalltalk/Cuis-Smalltalk-Dev @JuanVuletich
Can we follow Juan's guideance of of putting the documentation in a 'documentation' category in SystemDictionary, and then make that information visible from the help browsers? That will put the information in a well-known location for all distributions, and also make it presentable through the various help browsers.
Dave
On Fri, Jun 23, 2017 at 09:55:10PM +0200, Jakob Reschke wrote:
There are also the HelpTopic classes. WebClient has some IIRC. Since the texts reside in those classes, they would be placed next to the code in the package.
Am 23.06.2017 21:03 schrieb "Juan Vuletich" JuanVuletich@zoho.com:
On 6/23/2017 2:01 PM, tim Rowledge wrote:
On 23-06-2017, at 9:45 AM, Eliot Mirandaeliot.miranda@gmail.com
wrote:
To the general audience, I think information like the above is key to
being able to understand and exploit the system effectively, but where should it reside? Clearly "in my head" is not satisfactory. It belongs somewhere in the image, but it needs to be somewhere where people can find it and/or will look. Suggestions for an "architectural information" documentation section gratefully received. Object class>>whatIsAPrimitive might perhaps work or perhaps be overloaded.
A brief explanation in the sources as a comment for the class and/or
some relevant methods *plus* a link to a swiki page with the full details. The briefest explanation might well be as little as ???this is a quite complex issue; see swiki.squeak.org/85643505485"
tim
tim Rowledge; tim@rowledge.org; http://www.rowledge.org/tim Useful random insult:- A .22 caliber intellect in a .357 Magnum world.
But this information is for Smalltalk developers, not just for VM developers. And urls might eventually break.
I think the full information on how to better use the VM belong in some file in VM sources, maybe one or several .md files. And Smalltalk systems using the VMs might chose to duplicate it in the image. I'd surely do it for Cuis.
This might be too much for Object class>>whatIsAPrimitive. I think some methods in a 'documentation' category in SystemDictionary would be better. Or one (or several) new classes, just for this. Better if we can share them in all the distributions: Squeak, Pharo, Newspeak and Cuis.
Thanks,
-- Juan Vuletich www.cuis-smalltalk.org https://github.com/Cuis-Smalltalk/Cuis-Smalltalk-Dev @JuanVuletich
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 -- tim Rowledge; tim@rowledge.org; http://www.rowledge.org/tim Fractured Idiom:- PORTE-KOCHERE - Sacramental wine
vm-dev@lists.squeakfoundation.org