[PD] finding objects ?

[Jonathan Wilkes]

----- Original Message -----

> From: João Pais <jmmmpais at googlemail.com>
> To: Jonathan Wilkes <jancsika at yahoo.com>; Ivica Bukvic <ico at vt.edu>
> Cc: pd-list at iem.at
> Sent: Sunday, September 9, 2012 8:28 AM
> Subject: Re: [PD] finding objects ?
> 
> since the plugins/programs/pdwiki/whatever can't find the right object 
> because this isn't properly documented, why not create a group of 
> voluntaries that addresses the issue of a proper documentation? things that many 
> developers don't do, like:
> 
> - fill in the fields of xxx-meta.pd
> - make sure there is a help patch for each external (maybe even following the 
> pddp template)
> - since we're there, test the external, hopefully in several plattforms
> - add some relevant meta-tags for index searching
> - manage the tag list with more actualized indexes: the 0.help.list has very few 
> categories, some more could help a bit sort out the externals
> - add some content to the "related externals" subpatch
> 
> as there aren't that many objects being release every day, it wouldn't 
> be that much work.

There's probably a script that can be written to count the number of help
patches that still need META subpatches.  I have the feeling it's something
like 1500 or so.

> I would have no problem doing this, as long as there is some 
> waranty that my time won't be wasted by leaving the suggestions somewhere in 
> a mailbox, and not commiting the patches.

That's ultimately decided by the author of the library.  You have to contact each one
and ask if you can add those changes.  For some authors it's trivial.  For others,
like Miller, a separate location for the updated help had to be created because indeed
the suggestions just sit in a mailbox somewhere otherwise.

> 
> that would a) release the developers of the shore of doing a good documentation 
> (many don't really do it),

I think it'd be a better idea to assume that undocumented objects are either under
current development or are crap-- either way, they shouldn't be included in a release
of Pd.  In most cases a minimal example patch and a few sentences (or even single
words) to describe the xlet/object function is all that is needed.  If the developer couldn't
be bothered to do that, what else couldn't he/she be bothered to do in the code that
runs on your machine and can potential crash your patch?

> b) in the long run maybe have a unified 
> documentation for the whole pd-ext,

Without automated templates like matju's Gridflow documentation system this
is just too much work.

> c) give a model for new (and old?) 
> developers to prepare their material, if they want to,

See above.

> d) solve one big problem 
> with new users, the unstructured/unfriendly documentation, and e) world peace.

Unstructured docs are fine if they a) exist and b) are discoverable.

-Jonathan

> 
> João
> 
>>  Documentation is certainly just as important, if not more so. What I am
>>  suggesting is to build a framework that will be to some extent immediately
>>  useful, but also whose full potential well be realized only after all the
>>  documentation is properly updated.
>> 
>>  I'm also thinking about simply getting rid of any externals in pd-l2ork
>>  that don't have proper or at least half-decent documentation.
>>  On Sep 8, 2012 1:19 AM, "Jonathan Wilkes" 
> <jancsika at yahoo.com> wrote:
>> 
>>> 
>>> 
>>> 
>>> 
>>>  ----- Original Message -----
>>>  > From: Ivica Ico Bukvic <ico at vt.edu>
>>>  > To: 'Jonathan Wilkes' <jancsika at yahoo.com>
>>>  > Cc: pd-list at iem.at; 'Raphael Raccuia' 
> <rafael.raccuia at blindekinder.com>
>>>  > Sent: Friday, September 7, 2012 8:25 PM
>>>  > Subject: RE: [PD] finding objects ?
>>>  >
>>>  >>  I can update vcf~ in the PDDP docs at some point, but aside 
> from that
>>>  what
>>>  >>  do you have in mind?
>>>  >
>>>  > Multi-dimensional indexing whose data can be easily referenced by
>>>  multiple
>>>  > features (object search, auto-completion, maybe other)
>>>  >
>>> 
>>>  How will multiple dimensions help users find something that isn't 
> there?
>>> 
>>>  -Jonathan
>>> 
>>> 
> 
> 
> --Friedenstr. 58
> 10249 Berlin (Deutschland)
> Tel +49 30 42020091 | Mob +49 162 6843570
> Studio +49 30 69509190
> jmmmpais at googlemail.com | skype: jmmmpjmmmp
>