[PD] Patterns for Pd Documentation

[Esteban Viveros]

>
> 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
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.puredata.info/pipermail/pd-list/attachments/20210525/d0334667/attachment.htm>