[PD] Patterns for Pd Documentation

[Roman Haefeli]

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
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 488 bytes
Desc: This is a digitally signed message part
URL: <http://lists.puredata.info/pipermail/pd-list/attachments/20210525/6d564b49/attachment.sig>