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:
because of the care to register and create patches that are visually unified, that show a concern with good practices of patches creation.
http://www.cooperbaker.com/home/code/pd%20spectral%20toolkit/ which implements a simple and functional navigation mode.
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:
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! :)