Does anyone have a link, etc to the pddoc project/external from Pd-extended?
I feel a lot of this was already approached over 10 years ago but not ported over into Pd vanilla. It might be worth checking it out before starting from scratch.
Also, keep in mind that old habits may be hard to break so don't be surprised if enforcing "one pattern to rule them all" might become "whack-a-mole."
:)
> To point some examples of things already done in regard to better documentation:
> - Porres' ELSE documentation and the Live Electronics Tutorial are good because of
> the care to register and create patches that are visually unified, that show a concern
> with good practices of patches creation.
Thanks for the compliments.
Well. For ELSE and Cyclone I adopted a similar template than the ones above. They're all a bit different in design, but I think they all follow the same idea/concept, and here's the shocking revelation: I think it's a bad idea and I hate them!
I know it can be useful and helpful, but forcing any of these templates into every possible help file ends up in a nightmare in some cases. It might be good for most help files but there'll always be exceptions where it's just not pertinent at all to stick to the restrictions that were good for the other cases. Take my word after applying this over 600 times. I can say I regret it and would like to change it but it's just undoable at this point.
I'm totally onboard doing a complete rework of Pd's help files and contributing to the documentation in general. In fact, I've been doing a lot of that in recent times, by writing new manual sections and rewriting and fixing many help files. But I wouldn't embrace the idea of choosing a template for all. I wouldn't work on that and I can go on and on why I think it's a bad idea, giving many examples why I think this is bad, in opposition of anyone who thinks this is great and would like to do it themselves.
The one good thing about these templates is that they do offer a quick reference guide telling you what are the accepted messages, number of arguments and things like that. Sometimes you wanna get to this information very very quickly, immediately, as you're "in the zone" creating a masterpiece and don't want to interrupt the workflow for any second - but Pd Vanilla's help files force you to hold your horses for a moment and fish for that info.
I'm not saying we can't have that when I say the templates are problematic. I like that too! But I've been thinking of a different solution that doesn't involve forcing the same window area for every patch and having that kind of information right in the parent window.
In short, the options are:
- having a subpatch in a standardized way in the same spot of every help patch called [pd reference] with that info.
- having a html file, available with the Pd application and called from within the help patch, kinda like [slop~].
By the way, such a separate 'reference' information is sort of what we have in MAX, totally detached from the help file and its examples. For my work in Cyclone, I can say I hate MAX's documentation and that it is quite flawed, but I like this concept!
The easy option is to have this as a subpatch and this can also be done first as an initial step for the second option (where we can get the information and put it in a separate html file).
Cheers