[PD] Patterns for Pd Documentation

hans w. koch hansw.koch at gmail.com
Tue May 25 19:02:41 CEST 2021


as someone using pd in teaching in a german art academy context,
i agree, that sometimes the assumption that english = international is plain wrong (e.g. we have many korean students, for whom german is the second language and which are quite lost with english).

but i would like you to consider also a "two tiered” approach, based on my observations on how people learn: 
1. keep the english documentation as it is and maybe gradually introduce local translations into the helpfile patches with .po file strings (= a lot of work…)
2. around this core, try to coordinate the growing ecosystem of tutorial videos (very popular) available in many languages, also written tuts and blogs.
this, to have a kind of maintained ressources pool in all the languages. 
similar to this: https://puredata.info/docs/BooksAboutPd
e.g. how many people do know, that there is a spanish version of johannes kreidlers bang book, which -however outdated some of its content is- still covers a lot of ground? (i for one used it successfully in a short course with spanish only speaking housewives…)

reasoning:
the helpfiles as they are, are helpful only, if one already has some clues about the operation of pd. 
but then their (mostly) super concise style makes it easy to pluck information from.

but for construction patches / solutions to “real world” problems there is more often than not multiple ways to skin one cat.
and i´d say the more the merrier in any language.
the deeper one gets into, the easier it becomes to transcend the language barrier (thats my personal experience)
but beginnning is bloody hard in any language.

best
hans


> Am 25.05.2021 um 17:41 schrieb Esteban Viveros <emviveros at gmail.com>:
> 
> Reading this question makes me feel uncomfortable.  How would defining
> above criteria shape the way the documentation is going to be built?
> And isn't using that criteria to define the shape presumptuous, forcing
> you and me to make assumptions about groups of people you're/I'm not
> part of? IMHO, inclusiveness is not achieved with identity politics.
> Thanks thanks a lot for taking a stand and explaining gaps in my communication! What I pretend is to put ourselves open to welcome other points of view, welcome the needs of others than us when they surface. I don't know at this moment how to surface this need without some friction. Sorry about that and I think we can continue from the point of the explicitness of the need of welcoming diverse points of view.
> 
> I'm sorry for not giving you a more interesting/challenging view. I'm
> not saying the documentation cannot be improved, but I fail to see
> obvious problems with it. OTOH, I'm interested to hear about problems
> people face with the current documentation.
> I think you showed strong points of the actual documentation that has to be kept in a review if needed.
> 
> About the point 2. It is addressed to open the scope of feedbacks. I think that the effort to create a new standard for documentation should cover as many opinions as possible at first (like this one). It's like a brainstorm. Then we will try to systematize and organize the material we have in order to constitute a form that satisfies everyone as much as possible with easy maintenance, open to collaborations.
> 
> Thanks again Roman!
> 
> 
> Em ter., 25 de mai. de 2021 às 11:00, Roman Haefeli <reduzent at gmail.com> escreveu:
> Hi
> 
> On Mon, 2021-05-24 at 20:49 -0300, Esteban Viveros wrote:
> 
> > 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.
> 
> Reading this question makes me feel uncomfortable.  How would defining
> above criteria shape the way the documentation is going to be built?
> And isn't using that criteria to define the shape presumptuous, forcing
> you and me to make assumptions about groups of people you're/I'm not
> part of? IMHO, inclusiveness is not achieved with identity politics. 
> 
> I'm rather interested in what _you_ think is wrong with existing
> documentation and what _you_ think how it can be improved. I think this
> would lead to a more honest discussion. 
> 
> Just to give you one data point: 
> 
> For me the most important part is a comprehensive reference. Pd already
> covers what I need with the existing help-files (section 5) describing
> object classes and their supported methods. However, the reference is
> only interesting once you know how the language works and when you are
> familiar with its concepts. I learned Pd with the documentation it is
> delivered with. So, the sections 1-4 - for me at least - already did a
> great job at introducing me into Pd. Having said that, it took me years
> until I even tried to use data structures and I am not even sure I
> understand them now.
> 
> I'm sorry for not giving you a more interesting/challenging view. I'm
> not saying the documentation cannot be improved, but I fail to see
> obvious problems with it. OTOH, I'm interested to hear about problems
> people face with the current documentation.
> 
> > 2. Issues you see in actual way to document the objects, suggestions
> > to improve documentation to meet your imagined pd user.
> 
> Why imagined? What you think is already interesting I find. Also, you
> may have made your experiences with other Pd users and gained some
> insight from that? 
> 
> Roman
> _______________________________________________
> Pd-list at lists.iem.at mailing list
> UNSUBSCRIBE and account-management -> https://lists.puredata.info/listinfo/pd-list
> 
> 
> -- 
> 
>  Esteban Viveros
> 
> www.estebanviveros.com
> 
> 
> 
> _______________________________________________
> Pd-list at lists.iem.at mailing list
> UNSUBSCRIBE and account-management -> https://lists.puredata.info/listinfo/pd-list






More information about the Pd-list mailing list