[PD] Another request to replace Pd's docs by a "better one" (was: some gui objects with grey background in help patches?)

[Alexandre Torres Porres]

Hi. I assume nobody can take this discussion anymore, but the funniest
thing happened and I just have to bring it up here and make some further
considerations stressing things I already mentioned. I'm changing
the thread subject a bit to tell you about the case. In the discord channel
of "Plug Data" (a fork of Pd by Timothy Schoen) someone just requested
PlugData to adopt L2ork's help files instead of Vanilla's!

Didn't I say so? If you're only here in this mail list, you might miss
this, but on facebook groups, discord channels, classes and whatnot, you
get this ALL OF THE TIME and it just happened yet again today : )

For reference, here's the full message:

*@Timothy Could you consider replacing the *-help.pd files with the updated
help files found in L2Ork and PurrData? The default PD ones are filled with
landmines, for example if you open bp~-help, now you have to fight with the
dB box inside the little output~ graph. Just setting that dB to a correct
value is painful, I think you might find if you try it. When you open
bp~-help in L2Ork or PurrData the patcher is already locked and you can
toggle DSP in 1 click in the upper right in a reliable location, and the
docs are laid out nicer with iolet and argument descriptions. Granted some
of the text has been shortened and edited down which irks me but overall
the docs are more modern and have less legacy layout issues.*

There are several issues in this request and I'm getting into the
discussion. He's talking about the [output~] abstraction, which was
introduced recently, along with references (which are already in PlugData
by the way). So it's funny the complaint that L2ork has references (*iolet
and argument descriptions*) cause so does Pd! It's not on the front but in
a subpatch, and this is why I have an annoying "<= click" message to force
people to notice it and open it (maybe I should use a pink color?). While
we're at it, let me say I like the freedom of having a separate canvas for
references, it gives us flexibility that is useful in a few cases. By the
way, this is also how it works in the highly acclaimed and supposedly
superior documentation of MAX (you gotta click on a "*?*" menu and then on
a reference that opens in a separate window).

Anyway, I wish the problem and feedback was "I hoped the reference was
there right away as in L2ork and not in a subpatch". We could talk about
that, and I could explain the problems, like how do you plan to deal with
the help file of [expr] then? :) Btw, see how greatly this was managed in
Purr Data... (or don't and take my word it's not superior). But this is up
for discussion anyway...

It's funny how it was mentioned that clicking on the number box of the
[output~] abstraction, now present in [bp~]'s help file, is hard. I don't
know how much harder it is than clicking on a slider and how easier it is
to set the "right dB value" in a slider and what's really funny is that
Purr Data's example for [bp~] doesn't really have a better option to raise
volume as it has no usable example, nothing to output sound or listen to.
While Vanilla's example is now much superior with an actual white noise
being filtered so people can actually listen to it in action. Inlet
description and argument is also clear in the help file example...

Nonetheless, the perception is that this is all bad and how Vanilla's docs
is "*filled with landmines*"... but no real examples are given to support
how L2ork's is more "*modern and has less legacy layout issues*". I'll tell
you one thing though, it doesn't seem to be the fact that [output~] now
carries a bang whose background color is light grey and this stands out to
the eye as the only thing in the patch that's not either pure black or pure
white... the fact that l2ork's help file of float has a shiny light green
bang for no good reason, while other bangs are white does not seem to pose
a problem either.

Some might think this matter is stupid and silly, but I see it has quite an
important impact. It gives Vanilla an unfair bad reputation and rejection.
As you can see, I'm really committed and fighting for this cause. I always
heard how bad vanilla's docs were and it was a bit unfair as I could see
many problems and mistakes in Extended/L2ork. Ok, they had references in
most (but not all) 'vanilla' help files. I really wanted to revamp
Vanilla's docs for this and now we clearly have much more quality
information as a gazillion things were made, with countless revisions,
changes, additions and fixes - plus we now have newly written from scratch
references for ALL help files. So it is *really* unfair now.

Nonetheless, I see this feedback today! I guess that well consolidated
notions, unfair or not, are hard to challenge and it takes time. I busted
my ass a lot in the last couple of years and it still doesn't seem enough
:) I'm not giving up on this though...

I'm glad and proud that Vanilla's documentation today is much more superior
than any other fork. It would be maybe too much to expect that other forks
just grab this documentation, but I hope that in the next few years this
notion gets its deserved recognition. It's not that people aren't
recognizing it's getting better. There are many positive feedbacks, but
more things are yet to be done. Not sure yet what to do though. I don't
think we need to mimic the looks of L2ork to pretend we're now using its
supposedly more up to date and better revised content :) but I still see
that minor user interface details are still taken into consideration to
promote some sort of rejection and resistance.

So, this is also a heads up to 'old school' people that didn't feel
comfortable with some changes. As you can see, I'm still being somewhat
conservative. I won't get too crazy or do things "in the dark", but I will
study, I will think, I will ask, and I will probably include a bit more
'eye candy' things and other little details to make it more appealing
aesthetically. I will also describe the reasoning behind further changes,
saying how I based my decisions on what I gathered from feedback and
discussions in other channels than this mail list and stuff...

Please share your thoughts as well, of course. Also, this channel is always
opened ==> https://github.com/pure-data/pddp/discussions

cheers
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.puredata.info/pipermail/pd-list/attachments/20221125/a3d4b3ca/attachment-0001.htm>