[PD] translate the Start Here! page

[Jonathan Wilkes]

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

> From: Ed Kelly <morph_2016 at yahoo.co.uk>
> To: Jonathan Wilkes <jancsika at yahoo.com>; Hans-Christoph Steiner <hans at at.or.at>
> Cc: Pd List <pd-list at iem.at>
> Sent: Friday, January 4, 2013 8:47 PM
> Subject: Re: [PD] translate the Start Here! page
> 
>>  Also notice that neither you nor I are the least bit interested in fixing 
> these
> 
>>  problems in the FLOSS manual, and we're especially not interested in 
> taking
>>  it on as a long term project.  Who does that leave?  If it leaves anyone
>>  wouldn't their time be better spent fixing the doc problems listed on 
> the 
>>  tracker
>>  than etching in stone a description of a moving target?
> 
> 
> Well, if you have to teach Pd to art students who are used to using Photoshop 
> and Final Cut Pro (as I do) the FLOSS manual page is very useful to give them 
> some idea of what the objects are. It may not be 100% accurate, but at least it 
> is (only) a start. I do hope that the search mechanism replaces static docs 
> conceptually, but here is why they should be kept.
> 
> Learning Pd from scratch is not easy unless you are already a computer 
> scientist. "How do I know what the objects are called" is I agree, the 
> wrong question in so many ways.

Pd is basically just rectangles containing words, connected by lines.  Each box
should do one thing and do it well, to draw from the unix philosophy.  Lines
connect the input of one box to another so that complex problems may be solved
by combining many simple, clearly-defined building blocks to one another.

Aside from the particulars of controlling the flow of data through the diagram,
what other question is there than, "How do I know what the objects are called?"

> However, 80% of my undergraduate students 
> basically give up at that point if they can't find the answer, and probably 
> 60% of my masters students, often after saying "I hate Pd".

Of course they might also have just found out what happens when you try
to click "Undo" more than once in a row.  Or they projected a patch on a
screen for a demo and tried to enlarge the patch by making the fonts
bigger, and Pd mocked them by making a mess because well, they didn't
tell Pd to also scale the x,y positions and Pd isn't about to make any
assumption at all about what the user wants because then it would be
coddling them.

Also they can't change the colors.  Also in tk 8.4 the fonts hurt their eyes.
Also the tk menus respond to clicks in a slightly different way than native
tk menus.  Also moving an array (which also is limited to black and white)
not only causes dropouts but animates with speed similar to an Apple II.
Also every time they load a soundfile they are in danger of a dropout.

Also patches look slightly different on different machines so that Alice may
send perfectly designed patches to Bob but Bob sees overlapping text
and wonders silently why Alice is so sloppy.

Also any time they consider improving any of this behavior they are faced
with a graveyard of revisions by people much smarter than they are which
are way more elegant than anything they'd ever come up with.

Pd _clearly_ hates them from their perspective.  Provably, because as you
said they're already using advanced software that has tons of quality
documentation and teams of devs devoted to caring about how well-designed
the interface actually is.  And let's hope they don't come on this list and
see the general ethos that while Pd is barebones, real men build patches
from the ground up and eschew pre-fabbed solutions.  (Again drawing
from the unix philosophy.)  Fine, but somehow that translates into a
programming environment that's less accessible for people with vision
problems, and a single undo history?  That's absurd.


I wouldn't criticize them for not being Nelson Mandela.


> This 
> question usually comes up in the first lesson. I could criticise them for this, 
> except that there is an impression that Pd is "open" as well as 
> open-source. Is it? Or is it highly elitist? I think it can be both, but I 
> don't want to kick away the ladder...

It's much simpler than all that.


A program that has a single undo history quite simply _should_ suck
in the eyes of the beginner.  It sucks because it ignores the small amount
of memory a beginner has for visualizing in the language, and it sucks because
it ignores the enormous power modern computers have to store this history
for the user.  Again, your students _know_ this from working with programs that
require much more sophisticated command histories and deliver them flawlessly.
They should rightly be suspicious of how much of their limited time this
outlier software will actually require of them _before_ they can even start benefiting
from its intended design.

And single-item undo is just one small example.  Things like non-standard
navigation within a comment, mode-changes with a single, subtle piece of
visual feedback (the mouse cursor), and a lot else.  (But it's not an endless
list.)


> 
> Perhaps the problem lies more with "standards" for documentation 
> across the whole community - it's never going to happen (remember Pdpedia?) 
> because the Pd community can be somewhat anarchic. Hats off to Hans - making 
> Pd-extended work is like nailing jelly to the wall I guess.
No need for standards.  Write your help patches in any way you wish.  If you
want your objects to be found by category and look decent in the results of
the search plugin (as well as respond meaningfully when "Autotips" is enabled),
use [pd META], which you're already using because I bootstrapped that standard.
It's done.

At this stage I'm mainly concerned with the quality of these "anarchist" patches.
Here's another standard: if a help patch doesn't feature a clear example patch,
description of what all xlets do (with descriptions of what all methods do), description
of what all args do, then its a bug.  Done:

http://sourceforge.net/tracker/?func=detail&aid=3597385&group_id=55736&atid=478070


Btw-- the most non-conformist library, unauthorized, already conforms to my "standard",
which tells me we're not really talking about a standard but merely documentation
quality.


> 
> There are some small things we could do. For example, a description of what lies 
> in each folder of externals and what they are for may well be enough, followed 
> by a list of objects.

Already done.  In Pd-extended nightly build:
1) Click "Help" or <ctrl-h>

2) Click the "External Pd Libraries" link
3) View the "description of what lies in each folder of externals"
4) Click a link to get a list of objects, with a description of each object and link that
opens that object's help patch.


> My students are _scared_ of Pd because it is so utterly 
> different to anything else they have ever engaged with. A bit of documentation 
> that isn't in Pd itself eases the pain somewhat.


If you can calm them down enough to click <ctrl-h> they will be greeted by
the search plugin, and they will be tricked into believing they are looking
at something less scary than Pd.


> 
> A static web page will never be up-to-date since the pd externals folder is 
> always a moving target. But it is better than nothing.

I'm not comparing it to nothing.  I'm comparing it to the search plugin.


> It was really hard 
> persuading students to learn Pd when Flossmanuals didn't exist. It's 
> still hard, but it does open some doors to my students.


I'm only talking about the Object List in the Pd FLOSS manual.

-Jonathan


> 
> Ed
> 
>> 
>>  -Jonathan
>> 
>>> 
>>>   .hc
>>> 
>> 
>>  _______________________________________________
>>  Pd-list at iem.at mailing list
>>  UNSUBSCRIBE and account-management -> 
>>  http://lists.puredata.info/listinfo/pd-list
>> 
>