[PD-dev] Work on "help" menu and help-patch searching spec

[B. Bogart]

Ok,

Here is a sum up of comments made on list, I'm only pulling out the key
points and my comments.

ix at 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.
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 256 bytes
Desc: OpenPGP digital signature
URL: <http://lists.puredata.info/pipermail/pd-dev/attachments/20050426/dede576b/attachment.pgp>