Ok,
Here is a sum up of comments made on list, I'm only pulling out the key points and my comments.
ix@replic.net wrote:
my point exactly..between the unlikeliness of retrofitting all the help files, and no idea where it will be...sometimes its a #X text, other times its the name of a graph, or a message - i guess in the indexer would give KEYWORD: annotations a higher relevance in search results...
Consistancy between help files is sorely missed in PD. If we have a standard for help-patches then there is a template that is easily used for new abstractions. Indeed it is quite a chore to convert the old help files, but having a functional browsing and searching system should be reason enough for developers to convert thier own help patches.
Krzysztof Czaja wrote:
Have you considered other ways of browsing -- choosing something that better scales? Not sure if hierarchical pull-down menu is the right way of browsing thousands of items.
This connects to what HC says below about the catagories themselves. Is three catagories with 600 items each better than 9 subfolders with only 200 each? I think it is a scale of granularity, how much browseable resolution vs how much bulk listing. I agree that pull-down menus with 1000s of items is not a great solution (at least jumping with "p" works in pulldowns!!!) Maybe each subfolder does not bring up a list of objects but a new window containing a list of objects, with a little description of each and be able to link from this list to the help file.
Krzysztof Czaja wrote:
How would the help files structure relate to eventual structuring of class names into a browsable ``object list'' (btw. such list should have its own "open help file" popup)? And how would these relate to eventual structuring of classes themselves into packages, Guenter's namespaces, or anything that would finally be chosen?
Damn good question. I think what I'm imaging with the help menu is a kind of browseable object list. This need not be created on object instanciation ala max/impd but perhaps is just one in the same with the help menu. Or the object browser could be a separate floating window, that would deal with the 1000 items more easily. Each item would have a popup for "help" or "put". As for class structure this is a big issue, as I recall all the discussion around name-spaces was a solution to the name-conflict problem. These name-spaces are based on project name, not function. If the classes were organized by function then they would no longer solve the namespace issue, that is counter and cyclone counter are the same in terms of function. Mathieu, what do you think about how the help-menu, object browser and object namespaces relate?
Krzysztof Czaja wrote:
The structure seems closed. I mean, even though a keyword comment may contain any word that its author finds suitable, only the predefined words would categorize the file for browsing -- is this the case? and if so, why?
The central point here is that the structure of the browsing is user-centric and sorted by function. For this to be successful certain names/catagories would need to be standardized. If a new object does not fit into the existing catagories then A new catagory could be created for those items "other" ? I think the basis of the catagories need to be fixed, with the option of the developer adding more. I do not think leaving the community of developers to entirly self-structure will create a viable organization of objects.
Bryan Jurish wrote:
Agreed. Still, I think the option of adding one's own (arbitrary) keywords / structuring conventions is important too -- pre-defined hard categorization schemes have a disturbing tendency to go all goopy at the edges when they're not dictatorially enforced, which I don't think anyone here really wants to do or to be done; maybe the solution is just as simple as differentiating between "browsing" and "searching"?
Having a starting point functional organization that gets extended when needed seems to be like a fine solution. What other options are there? I *am* thinking of browsing and searching as being different. Searching is to find an object to solve a particular problem. Browsing is poking around to find out what is possible. Browsing being most important to novice users. I think fixed (general) catagories will be more meaningful than an automated clustering system.
Hans-Christoph Steiner wrote:
But I think at this point we need some basic implementation before we can really go into details. A simple hack that parses a pre-defined set of keywords from a specially tagged comment in a help patch would be relatively easy to implement. Then we can test it out, and take it from there. So... the question remains, who actually wants to do some implementation?
I've added a "deployment" page on the wiki: https://puredata.org/Members/bbogart/Deployment
Of course I imaging I'll be making a major contribution, since I'm pushing this approach.
Hans-Christoph Steiner wrote:
- The workshops should absolutely tie into the help system. That is
one of the key ideas of the open source workshops for me: that all of the materials would be built into Pd and integrated into the Pd help system.
I do think this makes a lot of sense. Miller, how do you feel about this? How do you approach the problem of teaching PD?
Hans-Christoph Steiner wrote:
- I think that if we have a search function, then the browse categories
should be as broad as possible, like just "control", "audio", "video" sounds pretty good to me.
By "broad" do you mean flat, as all objects fit into these tree catagories with no sub-folders? One thing I did not consider is objects that fit into more than one catagory. pix_sig2pix~ is an example right in the middle of audio and video. Maybe the help-patch format could allow one external to be in multiple catagories.
Ok thats it for me. Please feel free to post comments on the wiki so we end up with less information in email boxes.
Thanks for all the comments. B.