[PD] Patterns for Pd Documentation

Esteban Viveros emviveros at gmail.com
Tue May 25 17:16:03 CEST 2021


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 at 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 at lists.iem.at wrote:
>
> Date: Mon, 24 May 2021 20:49:37 -0300
> From: Esteban Viveros <emviveros at gmail.com>
> To: Pd-List <pd-list at lists.iem.at>
> Subject: [PD] Patterns for Pd Documentation
> Message-ID:
> <CAJQqjJRsQWxirbgOhr3kTT2q9Qydf5t9kSOU6QRJ-mB3yiokfQ at 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:
> 1. 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.
>
> 2. 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! :)
>
>
>

-- 

 Esteban Viveros

www.estebanviveros.com
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.puredata.info/pipermail/pd-list/attachments/20210525/20e5fcdf/attachment-0001.htm>


More information about the Pd-list mailing list