While we're at it, over my years in the Pd land, the feedback I got the most was how Pd Vanilla's documentation was so "poor" and "inferior" to, for instance, Pd-Extended's (not to mention MAX's). Currently Extended is reincarnated as Pd-l2ork/Purr Data, which are also praised as "better documented". So it kinda surprises me the feedback that things like this recent change makes it harder for newbies and more confusing. What to say then about the help file of Vanilla objects in Purr Data? If that's unknown, It might be a bit shocking :) There are bangs with inconsistent different colors, including a shiny light green one for no good reson (not to mention curvy lines). Anyway, for reference, find Extended's help file of [float] below.

I became a Pd user when, I don't know, maybe over 90% of people used Pd-Extended :) I'm designing a tutorial that I use to teach for about 15 years and it depended on Pd Extended for over a decade. Now it depends on ELSE which has a more discrete template design. I never saw anyone being confused by the complexity, colorfulness or whatever... on the contrary!

Pd extended is gone but I'm still not sure we've fully got over it. I've seen many people recently still sticking to it specially for didactical purposes, because of tutorials that are old and based on it, and because they think the cohesive and complete documentation is also better and the lack of need to learn how to install externals is another didactical advantage. Pd-l2ork & Purr Data serve this purpose well. 

So, what I've seen is that people usually have a hard time adapting to Vanilla's simpler design and documentation. Also, I've seen requests for improvements in this sense and even people feeling as if Vanilla was outdated or seemed abandoned in comparison to extended/l2ork/purr... one factor being the help files, surely.

My motivation to revamp Pd Vanilla's documentation is highly motivated by this context. I take most of the bad reputation Vanilla's documentation has comes from its sheer simplicity, which I actually don't have a problem with, mostly. I considered such assumptions to be rather unfair and more of an aesthetical impression favoring format over content. 

When dealing with recent changes to Pd's documentation, I can say there were requests to copy the model of Pd-extended/Purr Data into Vanilla or use it as a basis. Funny how people have different desires and expectations, right? Where I'm getting at is that it is really hard to reach a 100% consensus and that diverging ideas will always happen...

There were things that really made sense to incorporate from extended, such as "references" for all objects, so I did it. I offered resistance in simply adopting the extended standard and tried to meet halfway... my perception is that Extended's documentation had lots of noise and distractions indeed, and it is quite divergent from the original. So i just worked on top of the original trying my best to not be intrusive. Besides adding "reference" information, I also proposed minor cosmetic changes and a discrete new template again taking into consideration feedback from people that had some resistance to Vanilla's documentation, trying to make it a bit more appealing aesthetically towards the direction of something I always heard complaints about. 

The point I am making is that there are thoughts on my side on what people mostly want, despite possible divergences. When proposing such things, I'm taking it all into consideration. The general feedback from the facebook group (with no negative feedback so far) seems to point to the fact that the acceptance is mostly good, as I expected. 

The other point is that I've been teaching Pd for about 15 years to hundreds of people - using Pd extended, Purr Data, Pd Vanilla with external libraries that have different and colorful help templates (Cyclone, ELSE, FFTease and others) - and not ever has anyone gotten confused or thrown off by any of this! Not once!

Not to mention the fact I also eventually use MAX in classes and refer it to Cyclone. People deal with it just fine and easily also understand that a bang in MAX is the same thing as a bang button in Pd effortlessly. Recently I started presenting "Plug Data" into my classes, which carries out of the box Cyclone and ELSE and offers a divergent "MAX like" design of bang buttons and stuff altogether. Again, all fine, no problem... people get it, really. 

This is why I say I can't see how this may generate such concerns. Of course, other's mileage may vary, but I'm just being honest into what my experience has been over the years.

Cheers.

Em dom., 20 de nov. de 2022 às 16:51, Alexandre Torres Porres <porres@gmail.com> escreveu:

Em dom., 20 de nov. de 2022 às 15:07, José de Abreu <abreubacelar@gmail.com> escreveu:

Hello all, ok, some thoughts about the topic.

I think it would be nice to have colors with meaningful information, we currently don't have those, indeed just a grey color background doesn't transport any information, it is just an aesthetic decision, as porres stated. As it is, it doesn't make much difference if we have them or not... and as the discussion is going on here, people seem to prefer without them

I wouldn't take a discussion here as the consensus. Because of that, I had opened earlier today a poll on the facebook group, as that seemed like a better place to get a general sense. See: https://web.facebook.com/groups/puredata/posts/10159688754069495

I know not all here have facebook, but, so far, out of 24 votes in the 5 hours it's been on, no one really opposed. We have 15 people that actually like this and 09 that feel indifferent. Hence, I would take this as something that has more of a positive feedback as a general consensus than a negative one, at least for now.

You have a complex take on this by the way. It seems we have similar ideas that this is not a real distraction/confusion as people should be curious and copying from help files wouldn't really be a problem, but you're also taking other things into consideration and proposing yet more colors and complexity, which I think is another conflicting perspective to what was previously brought up as a problem here.

I guess that opening a github discussion about documentation ideas and issues is maybe a better place for what you're bringing, cause it's sort of a digression. Would you open it?

And also, I would like to stress that I don't call the shots and I didn't do this n the dark. I propose changes and usually people bring stuff up if they oppose it on github. Not a lot of people are there of course, but anyone who cares can join and discuss, propose stuff. For reference, here's the pd documentation project https://github.com/pure-data/pddp

cheers