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."
On May 25, 2021, at 1:50 AM, pd-list-request@lists.iem.at wrote:
Date: Mon, 24 May 2021 20:49:37 -0300 From: Esteban Viveros <emviveros@gmail.com mailto:emviveros@gmail.com> To: Pd-List <pd-list@lists.iem.at mailto:pd-list@lists.iem.at> Subject: [PD] Patterns for Pd Documentation Message-ID: <CAJQqjJRsQWxirbgOhr3kTT2q9Qydf5t9kSOU6QRJ-mB3yiokfQ@mail.gmail.com mailto:CAJQqjJRsQWxirbgOhr3kTT2q9Qydf5t9kSOU6QRJ-mB3yiokfQ@mail.gmail.com> Content-Type: text/plain; charset="utf-8"
Hello list! I'm looking for beliefs, judgment, advice, and anything that can contribute to better documentation of the entire world for pd users only.
I suggest explicit 2 points:
- What is the audience that you believe will make use of the Pd
documentation? Things like, advanced english speakers, academics, the gender, low/high earning power, if they are programmers, musicians, open source people, nationality... whatever you can write in a few words.
- Issues you see in actual way to document the objects, suggestions to
improve documentation to meet your imagined pd user.
Educational experiences, examples of documentation patterns, opinions about how things have been done so far are welcome! If you want to contribute more in effort to improve Pd Docs Structure I have opened a issue in Pd github: Pattern design for Pd Documentation <https://github.com/pure-data/pure-data/issues/1320 https://github.com/pure-data/pure-data/issues/1320>
Thanks for all! :)
Thank you Dan for the tips!
Right now I think the discussion of documentation is centralized in educational practice inside academic environment. I had contact with the Pd in this environment but now I see a lot of people having contact with Pd inside free workshops, which brought other ways to search for information.
An example is here in Brazil, I noticed that the English language has been a big obstacle in the tool's learning path. Even for teachers who teach classes to teenagers. So I have been thinking about ways to alleviate the difficulties, which inevitably involves supporting multiple languages in the documentation. There is a discussion about this in the list <https://lists.puredata.info/pipermail/pd-list//2016-02/113597.html >.
There are various insights about efforts to provide support to multi-language patches inside Pd, move the focus of objects reference to html files to be opened on browser and called from Pd patch. There are to references about Processing and OpenFrameworks docs https://lists.puredata.info/pipermail/pd-list//2016-02/113613.html and a draft survey of possibilities to provide a platform that allows the inclusion of content tutorials regarding synthesis techniques and everything else.
Personally I believe we have a lot of work done using this information and the help patch models done in Pd-extended. Would be great if we can find this documented.
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.
- Recently I find Pd Spectral Toolkit Documentation
http://www.cooperbaker.com/home/code/pd%20spectral%20toolkit/ which implements a simple and functional navigation mode.
- Now we have http://msp.ucsd.edu/Pd_documentation/index.htm#s2, which is
shipped with Pd which start to provide information in html, but without multi-language support and with confusing visualization. You can’t understand if it’s a tutorial or documentation by topic. In that way Pd Spectral Toolkit Documentation http://www.cooperbaker.com/home/code/pd%20spectral%20toolkit/ was more successful.
I started to asking about in Pd patch repo, telegram Pd group, discord and Facebook, and there at this moment people sent:
- https://gridflow.ca/help/ - which I see interesting the use of colors in
the patch which is more apelative to the eyes. But to go in this way mapping the audience is required.
Another very blowing mind in my view, which amplify the scope of the problem in my point of view is the mscotthouston post on github related issue https://github.com/pure-data/pure-data/issues/1320#issuecomment-847909602, he reach at github issue from a call I did in pd discord channel.
Please, disagree, propose and take a stand. This way, it will be possible to map a little of what the pd community needs in new documentation.
Em ter., 25 de mai. de 2021 às 05:48, Dan Wilcox danomatika@gmail.com escreveu:
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."
On May 25, 2021, at 1:50 AM, pd-list-request@lists.iem.at wrote:
Date: Mon, 24 May 2021 20:49:37 -0300 From: Esteban Viveros emviveros@gmail.com To: Pd-List pd-list@lists.iem.at Subject: [PD] Patterns for Pd Documentation Message-ID: CAJQqjJRsQWxirbgOhr3kTT2q9Qydf5t9kSOU6QRJ-mB3yiokfQ@mail.gmail.com Content-Type: text/plain; charset="utf-8"
Hello list! I'm looking for beliefs, judgment, advice, and anything that can contribute to better documentation of the entire world for pd users only.
I suggest explicit 2 points:
- What is the audience that you believe will make use of the Pd
documentation? Things like, advanced english speakers, academics, the gender, low/high earning power, if they are programmers, musicians, open source people, nationality... whatever you can write in a few words.
- Issues you see in actual way to document the objects, suggestions to
improve documentation to meet your imagined pd user.
Educational experiences, examples of documentation patterns, opinions about how things have been done so far are welcome! If you want to contribute more in effort to improve Pd Docs Structure I have opened a issue in Pd github: Pattern design for Pd Documentation https://github.com/pure-data/pure-data/issues/1320
Thanks for all! :)
Em ter., 25 de mai. de 2021 às 05:50, Dan Wilcox danomatika@gmail.com escreveu:
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.
this? => http://puredata.info/dev/pddp/pddp-drafts
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
By the way, one thing that is very useful for ELSE's help files is my [display] object (similar to Extended's [PRINT] from 'pddp') that can print any data from the outlets right on the patch, which is something people seem to hope for in a friendlier documentation - [display] also flashes when receiving data.
I have a solution for atom boxes that I already proposed in https://github.com/pure-data/pure-data/issues/1321 I could give it a try in a PR.
But Pd would still need an object for 'anything', an 'anything' box (yes, a newly compiled GUI object), or an abstraction like [PRINT]/[display]. In order to ship it as part of Pd, it makes better sense to me a compiled object, instead of a new 'extra' object. Unless we have this abstraction as a helper abstraction for the help files only. Pd already does something like that with its 'output~.pd' abstraction.
By the way, recently, we've been discussing if 'output~.pd' should be part of 'extra', because we're using it in 3 different places (that is, we have 3 different copies of it): - in the help files folder (5.reference), in 3.audio.examples and 4.data.structures. I can't find now where me and IOhannes were discussing it, but it's somewhere on github.
I don't think it's worth 'promoting' output~ to extra, but I wouldn't oppose it either. I'm also unsure about having something like [display] in extra. I don't have a strong opinion on this though and I could go either way with the crowd.
What I think it's important is that we have an object to help us in the documentation, so my strong opinion is that we should find a solution. A compiled 'anything' box would be nice, but I don't think I can easily do that myself, so my offer is that I can design a vanilla abstraction like [display] - first as a helper abstraction (not an 'extra' object), and that's it.
Cheers
Em ter., 25 de mai. de 2021 às 13:51, Alexandre Torres Porres < porres@gmail.com> escreveu:
Em ter., 25 de mai. de 2021 às 05:50, Dan Wilcox danomatika@gmail.com escreveu:
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.
this? => http://puredata.info/dev/pddp/pddp-drafts
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
-
Alexandre Torres Porres -
Dan Wilcox -
Esteban Viveros