Hello! I'm in effort to make Pd documentation better. To map what we need to do, I'm starting to ask Pd community. So you can help responding 2 questions:

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:

https://github.com/pure-data/pure-data/issues/1320

Oh, but FLOSS manuals has a nice tutorial for begginers...

Well, there are lots of tutorials out there...

This tutorial is based on Extended and is very very old and misses many new stuff

If you think we should also have a new tutorial to replace this, well, it needs to be a tutorial based on Purr Data, I guess, which is the alternative to extended these days. So, well, not related to Pd itself, but a fork of Pd... but that's a separate project, a Purr Data project. Unlike Extended, the gap from vanilla to Purr is huge and it's just hard to work on something that's suitable for both. As a community, we should also make things like that clear to avoid noise.

On the other hand. If you want a new tutorial like the FLOSS one for 'vanilla' as part of its official documentation, then we need to work on it from scratch, and there'll be no need for a FLOSS version that lives in flossmanuals.net! And I think that can easily be included as part of the Pd Vanilla distribution and its online documentation.

If you're actually unhappy with a 'all and pure vanilla distribution', meaning, you use Pd Vanilla, but you have dozens of external libraries and can't live without them, then we have another issue. How to work with a tutorial that uses some of the external libraries out there? What libraries are worth using? Which are abandoned? How are we gonna have a tutorial inside vanilla that uses external libraries?

I think this can be done too... well... in fact, I have one tutorial myself, and it only needs one single library called ELSE... and it actually comes as part of ELSE. And you don't need to do anything else other than just using deken to download it and use it...

See? How easier could it be? Anyone can design a new tutorial that uses externals and just give instructions on how to download them via deken and use it. We can point to these as part of the OFFICIAL Pd documentation and just forget about FLOSS...

@porres said in Contribute to better Pd Documentation:

On the other hand. If you want a new tutorial like the FLOSS one for 'vanilla' as part of its official documentation, then we need to work on it from scratch, and there'll be no need for a FLOSS version that lives in flossmanuals.net! And I think that can easily be included as part of the Pd Vanilla distribution and its online documentation.

So, went to have a look as to what would it take to make the FLOSS tutorials ported to vanilla... and... well, it seems that despite using Extended, some of the examples are pretty much 'vanilla friendly' (no externals). These can be easily ported then...

But where are the authors these days? I know Derek Holzer is one, but he was just recently sayin on the facebook group that the FLOSS manuals is old should be forgotten himself... If we were to update it in the web, who would do it? And could we revise it and change it and take or put stuff?

Well, I'm thinking about copying the basic tutorials here into a new one, fully vanilla, to be downloadable via deken. But... I guess it'll be kinda "based on this", because I have a few issues with some of the things we have here.

For instance, [phasor~] is described as an osccllator, and it is not one in the sense you can plug it in and listen to it as it has a DC Offset. I will suggest that we even change the description in the help object from 'sawtooth' generator to 'phase ramp' generator. Oscillators need to go from -1 to 1. The square oscillator there is also a pulse train instead. And these are not band limited oscillators (so pretty bad and aliased ones) and we should say that...

Also, in ampplitude modulation, I don;t think it's a good classical example to modulate it to a phasor~ signal, an [osc~] should be much better. And the 'tremolo' effect should also have a 'depth' parameter so it can be called an actual tremolo. A tremolo is not just amplitude modulation with a low frequency.

So if I were to design a new and quick, simple, new tutorial for newcomers, I know I'd change a lot of things... so the problem I have with it is not that it's just old and outdated, but also with the content, which I think can be greatly improved.

I created a new issue on github https://github.com/pure-data/pure-data/issues/1331#issuecomment-850893517

@emviveros It looks like you need to sign up here https://www.flossmanuals.org/get-involved-0, they disabled the simple account creation due to spam issues. I have filled it out to see about getting signed up to edit it, I am not much good at writing documentation but there are some areas I can improve. This seems a worthwhile project considering that this manual is often on the first page of google results for any question about PD and getting it updated also gets the multitude of links and references to it up to date at the same time. Hopefully a few others from the community will also join in to update it.

1. Put all the help + tutorial files in a new repository on GitHub.
2. Allow much more people to have admin rights.
3. Let the community handles that in a centralized place without interacting with the core team.
4. Make it a safe and friendly area (for newcomers).
5. Note that more you have materials for documentation, more energy is required to maintain/translate it.

My 2 cents.

@oid said:

This seems a worthwhile project considering that this manual is often on the first page of google results for any question about PD

It's within the main search results and references out there for sure. But I couldn't reproduce it being the first result in google - puredata.info is always the top one when searching for "pure data", "pure data tutorial", "pure data documentation", and even "pure data manual" (I tested this on a 'clean' history).

One way or another, puredata.info is the one thing that needs attention more ungently and we can quickly do that (in seconds) by just saying "FLOSS manuals is outdated and deactivated". If it ever gets updated, great, we change it as "updated, reactivated and currently maintained".

I get your concern and how useful it'd be that this would just keep up as a good resource. Yes, there are links to this reference even in Pd's manual. But links can be updated too, or even removed. And if something it's just abandoned and can't get its references/links to new stuff or whatever, well, sometimes old stuff out there have references/links to things that are also old and that's life. We don't necessarily have to work on something because it was once great. Things change, time changes and for practical purposes, things can be renewed, replaced.

I made some points as to why I think that keeping a parallel Pd Manual online is now a bad idea. It made sense when it represented extended, but not now. So if anyone thinks it's a good idea to keep working on FLOSS Manuals, I would really like to hear your thoughts on what I brought up here - like my idea that it can add noise and be counterproductive, that we can have a single and unified manual as part of the official documentation instead.

@Nicolas-Danet said:

Put all the help + tutorial files in a new repository on GitHub.
Allow much more people to have admin rights.
Let the community handles that in a centralized place without interacting with the core team.
Make it a safe and friendly area (for newcomers).
Note that more you have materials for documentation, more energy is required to maintain/translate it.
My 2 cents.

I don't know if I really get what this proposal is. Are you saying we should have yet another parallel Pd vanilla documentation on github for help files and everything? The end goal would be to actually merge this into the Pd documentation?

Sorry if I'm wrong, but it sounds like you're proposing yet another independent joint venture, and that would generate more noise, I believe. I say that specially when you say this should be done "without interacting with the core team", so it really sounds like you want something independent and I wonder why.

I'm also just not sure what 'core team' is would even mean. Who is the 'core team'? There's no actual 'team'. Pd Vanilla is developed and maintained by one person: Miller Puckette. Ok, he is not the only one who's done stuff for Pd, others help and contribute to the project, and he picks/accepts stuff. So it is Miller's project with the collaboration of others as a community. No one else has a 'pd core team' work tag and ANYONE can just send a Pull Request.

For instance. I've been contributing to Pd Vanilla with suggestions, bug reports and some PRs. Am I part of the 'core team' (and thus maybe I shouldn't interact)? Well, I would never say I'm part of the core team... I'm just a random person contributing to an open source project called Pure Data by Miller Puckette as part of someone from the Pure Data community.

Anyway, this thread links to a Pure Data github issues. That's on Pd Vanilla's repository. The idea is clearly to work and propose changes to Pd's help files, the manual, propose new stuff to the software. You seem to suggest nothing like that happens and we start something new and independent from scratch as a 'community effort', putting in opposition the 'community' and the 'core team'. If I'm right in my assumption, this sounds really bad to me as it has a divisive mentality, which I think is responsible for all the noise we have when it comes to Pd's documentation.

@porres: Was just something about < https://docs.github.com/en/organizations >, an usual approach to manage collaboration with various levels. Oh i've been downvoted.

@Nicolas-Danet I neutralized your downvote.

@Jona Thanks. I'll sleep better tonight.

It's funny how people don't just assume they can help and contribute to Pd's documentation. I don't know where that comes from, really.

@Nicolas-Danet said:

Was just something about < https://docs.github.com/en/organizations >, an usual approach to manage collaboration with various levels. Oh i've been downvoted.

ok, I got it wrong then, so upvoted now but I still don't know what you mean by creating a new repository without interacting with the core team, this link did not clarify it to me. Is the idea then to create something and then merge back into upstream? Why not a fork then?

And I also don't get why you're quoting me saying I don't get why people feel there's something preventing them from collaborating to the documentation. I've never seen PRs like that getting rejected, I've written a new section on the manual, many help files, so if you have something to add to the discussion, please share.

@porres First page not first result. For your same search and no history I get the floss site for the 4th, on duckduckgo it is the 3rd, the first result which is not puredata.info on both. So a good number of people are clicking that link. I would say the Floss manual is aimed at a different audience, those who want analog style sequencers instead of markov chains. It serves a different purpose than the manual.

yeah, I contributed to it in 2009 and there are some cool things there, I'm not sure exactly what to do with it, but I have a new thread https://forum.pdpatchrepo.info/topic/13479/pd-floss-manual-what-to-do-with-it

@porres For instance on my fork i put all the tutorials outside of the software repository < https://github.com/Spaghettis >. I created an organization that owns all the stuff. And thus i could give easily the rights for anybody to work on those tutorials, without to care to add noise into the main development. I could even give push rights for an user (that have no idea about C/C++) without fears (for me and him/her/it) to make something wrong. In my case i don't have time to spend in large debates, and such with that approach i would quickly give/split responsabilities to avoid to blow my head. Anyway that is only speculations, since in my case i have zero user, and in your case as you said:

Pd Vanilla is developed and maintained by one person: Miller Puckette.

Something like that < https://github.com/pure-data/pddp >?

@Nicolas-Danet said:

Something like that < https://github.com/pure-data/pddp >?

yeah, I see it now, IOhannes has just proposed the same thing, see https://github.com/pure-data/pure-data/issues/1333#issuecomment-851315723

we're on it

The PDDP repository is... pure. A very very pure solution. No content, thus no issues. Awesome!
Is somebody know what is it supposed to be? That: https://puredata.info/downloads/pddp?

@Nicolas-Danet PDDP was the complete Vanilla help within Pd Extended (I mentioned it above).
It contained style sheets and hyperlinks....... basically what you are all looking at accomplishing now..... but already done for Vanilla (within the Extended download) in about 2012.
That is why I suggested tweaking it for the latest Vanilla.
There was far more "help" within it than the current Vanilla help.

If you download Pd Extended......... https://puredata.info/downloads/pd-extended it is certainly contained within the source code (the tarball I think).
No idea why it has been deleted from its dedicated puredata.info page.
I have often recommended that people grab it when they are stuck..... it is very helpful.

Once you have the source code uncompressed just do a search for PDDP.
That will list all the Vanilla help files in the doc folder and the pddp folder that contains the files necessary to set it up as a service on a server.
David.

@60hz I'm late to this thread but I only wanted to say that your help files look completely amazing, particularly your help-intro.pd! I've taught Pd in a lot of different ways and I can absolutely see that being extremely helpful to new users. well done!
this is a very wide-ranging discussion, but it's great to see a vision of an approach to some of these issues.

@yannseznec
Thanks a lot! I mixed and modified the work of many people for the interface, and I regulary make change to many help patches and it works better and better with students (I use a top down logic). I hope one day pd will be easier to learn and I won't need this anymore