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...
cheers