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

It is a great idea and should be useful to everyone.
Unfortunately so many people never see the doc folder though except when they access vanilla help files and even then are blissfully unaware of its existence.

Maybe adding a "Documentation" link to the console help menu would be a good first move....?
The doc subfolder names are not enticing..... "3.audio.examples" really could be "3.digital.audio.tutorial" for example.
I don't think there is even a link to it in the "HTML Manual" which becomes "PD Documentation" when it is opened.
All very confusing though as the Pd.doc folder is mostly a patching tutorial that complements the Floss manual.

You have probably seen that @beem is working on a wiki..... https://forum.pdpatchrepo.info/topic/13054/starting-a-pure-data-wiki-database-examples-collection

Hyperlinks are the past and the future and the object help files in extended had quite a few...... although many are now dead.
David.

@whale-av said:

Maybe adding a "Documentation" link to the console help menu would be a good first move....?

I agree, if only clickable link could be added to console.

The doc subfolder names are not enticing..... "3.audio.examples" really could be "3.digital.audio.tutorial" for example.
I don't think there is even a link to it in the "HTML Manual" which becomes "PD Documentation" when it is opened.
All very confusing though as the Pd.doc folder is mostly a patching tutorial that complements the Floss manual.

I agree, the documentation could a bit more explicit and well organised. I simply don't use it and added mine.

Finally, Here is an example of my pd version that I throw to students now to have a chance to keep them in the game:

• I am using ceammc a lot, and added some objets and a simple theme:
  

• I added a template for every new patches and some personnal icons to ceammc bar:
  

• Here is my Intro-help.pd (accessible from any right clic in a patch)
  

• I added my own fast prototyping ofelia abstractions:
  

• The right click show all the objects (also have auto-completion of course)
  

I think right-click on objects should propose "Online Reference" that lead to an online up-to-date documentation... or wiki.

We are open to change to a new wiki system, hosting, etc. But for starting I think it's great.

I totally agree with an "online reference", max objects have it we could too

Sorry for the offtopic question @60Hz but how can I change the color theme in Pd-ceammc?

We are open to change to a new wiki system, hosting, etc. But for starting I think it's great.

That's great yes, lot of useful stuffs already on the wiki that replace all my bookmarks (I will add some others soon). But we need to be aware that finding too many informations on multiple websites might be confusing for new user. And all need to be maintained because up-to-date today's informations will become tomorow obsolet's one...

So I think what would be nice is to concenrate all efforts to make puredata.info website up to date and also Floss manuals, wich are well referenced and will be find by many users at first.

I totally agree with an "online reference", max objects have it we could too

Yes, really. But that needs to modify pd sources...

Sorry for the offtopic question @60Hz but how can I change the color theme in Pd-ceammc?

I use Pd-Vanilla, and added ceammc externals and ofelia only.
So pd-next which is vanilla puredata + closebang, initbang and color themes...

also Floss manuals

There is also two floss manuals that are almost identical, one has a yellow sidebar, is more complete and lacks the broken link for Dataflow->Math but is more difficult to find, google always brings up the other one. with the white sidebar, you have to dig through the floss site to find the other. Completely forgot about that, had meant to look into fixing that ages ago but life got in the way and I did not have time to figure out Floss. Would be nice to have the more complete one be the on google retrieves.

EDIT: Does anyone else know the yellow sidebar floss manual? I am having trouble finding it. I know the last time I looked for it I ended up having to dig through old bookmark files to find it.

The doc for extended was 9.32Mb..... but included 5.96Mb of media.
The doc for vanilla 0.51.3 is 2.85Mb
A difference of 0.5Mb-ish without the media...... so quite a lot of text.

but are you counting the help files of dozens of libraries it had?

Maybe adding a "Documentation" link to the console help menu would be a good first move....?

Hmmm, but there's already a link to a Pd documentation in html right there in the help tab, and we also have the browser which has the same manual section and other sections. Why do we need it in the console?

The doc subfolder names are not enticing..... "3.audio.examples" really could be "3.digital.audio.tutorial" for example

that's actually the examples from Miller Puckette's book and they should be read alongside his book

I don't think there is even a link to it in the "HTML Manual" which becomes "PD Documentation" when it is opened.

No, it's a separate thing, it's not part of pd's documentation per se.... it's something else (the book's examples) that comes as part of Pd.

All very confusing though as the Pd.doc folder is mostly a patching tutorial that complements the Floss manual.

I don;t know why you call this the 'Pd doc' folder, it's the control examples, and yeah, it's like a quick start tutorial, also by Miller.

I totally agree with an "online reference", max objects have it we could too

I actually suggested that on the Pd list, but what do you mean by it? I'm thinking pretty much like how it works on MAX, with a detailed and quick reference for each inlet and what message it takes, as a companion to the help file.

@60hz said:

Yes, really. But that needs to modify pd sources...

how so? Pd already carries html examples, like the very own Pd Manual, and you can also open html files from within a help patch - the slop~ object does exactly that and calls a reference html file to explain how the filter works. We'd be doing that just for the other objects/help files.

So I think what would be nice is to concenrate all efforts to make puredata.info website up to date

I agree that website needs attention as it is the one thing people find first and has all the links to all manuals, this forum, the pd-list and what not. And I also see here new links to other resources, but then, when talking about the 'Pd Documentation', I understand we're talking about the help files, it manual and things that comes with the application, not all online resources and tutorials out there. And it's hard to think about that because, yeah, lots of stuff is just outdated, like the FLOSS manual (but that's from an independent third party author and not really part of 'Pd's official documentation')

EDIT: Maybe doing a cleanup on puredata.info could help in saying what resources are more up to date. We could have an 'old archive' section for things that are just too dusty...

But the doc Pd/doc/5.reference had more elaborated help files .
Hava a look...... ext_v_vanilla example-route.zip
With hyperlinks and demonstrative subpatches.... a massive amount of rewriting had been done already...... now lost to anyone without Extended on their computer. It was called the "PDDP Project".
The extended help files were also better formatted and so "prettier"........ although opening the extended help-file in vanilla will not render the patch as "prettily" as extended you will still see the difference.
There was a PDDP style guide and a css style sheet associated in extended...... pddp.zip

In the vanilla help files some essential information about vanilla objects is also missing..... see conversations I have had with @ddw_music recently on this forum.
If I get time this weekend I will search for them and post a summary.
David.

But the doc Pd/doc/5.reference had more elaborated help files .
Hava a look...... ext_v_vanilla example-route.zip

yeah, but some of that is kinda wrong or unnecessary in my point of view (talking about this specific example). More doesn't always mean better if some of the information is not that good.

The thing about it having a 'type_mode' is simply not true and misleading. A lot of the data there is just unnecessarily confusing.

@whale-av said:

In the vanilla help files some essential information about vanilla objects is also missing..... see conversations I have had with @ddw_music recently on this forum.
If I get time this weekend I will search for them and post a summary.

please do, it's easy to file an issue on github with whatever you find is essential or missing or wrong or misleading. If no one does that, then no magic happens. I've been able to make extensive contributions to the help files of Pd Vanilla recently. It's funny you mentioned the help file of route as I've recently worked on an update of it, see https://github.com/pure-data/pure-data/issues/1302

The pddp format has advantages, but also disadvantages, try doing the expr family of objects in that standard, it's good extended did not try it. Anyway, I worked on the documentation of cyclone and I also have my own library with over 420 help files that that use a similar standard. Trust me, after over 600 cases, you'll see how this format can be a bit of a nightmare.

What is good about this template is the quick reference guide. But for that I'm proposing a separate 'reference' guide like in Max, which can be a html file that we can open from the help file, or a subpatch at the very least.

@oid I think the old "yellow" Pd floss manual has gone to book form.
From my vague recollection it was this....... https://en.flossmanuals.net/pure-data/_full/
Not absolutely certain but the photos in it look familiar.
But unfortunately the other language versions seem to have gone......?
David.

Maybe this: http://archive.flossmanuals.net/pure-data/

(?) The new Floss: http://write.flossmanuals.net/pure-data/introduction2/

It have a very simple layout, and the beatiful concept which is links to objects source code.

How discussed in Pd-list, the translations can be done via html file, which can be shipped with Pd, in fact as it is already done how @porres says, but disponible online to, like Max does.

What I can think regard organizing the topics I catched are:

1. Update puredata.info to clarify the situation of unofficial documentation, list and classify it about updated ou dusty.
2. About how to internationalize help patches information. I can't find much propositions in this way of how to do, but I think a good way is embrace the html documentation.

Another idea:

• A Welcome to Pd in the first install can be great to newcomers. That Welcome might have information about how to use documentation, which can reduce misunderstandings about where to get information from Pd

If somebody knows how to edit floss, we can make a new effort to update it. Now I'm thinking more in:

1. provide better documentation inside official Pd envyronment, which includes pd-help-patches/html ways to reference pd docs offline and online with multi-language support,
2. reorganize puredata.info to update infos about unofficial tutorials and
3. ways to access online References from Pd.

that's over a decade ago and extended is no 'Pd', it is a fork of Pd, which is abandoned anyway, for almost 10 years now...

I get it that many people still find it and use it, but that's just bad. This should be one of the things heavily marked as OUTDATED in puredata.info and just forgotten about... or... completely rewritten mostly from scratch.

Now, here's one thing. Why are we writing a separate and independent manual for Pd?

Is Pd's manual not good enough? Why? What's missing?

Where I'm getting at is, FLOSS was written way long ago, when nobody used vanilla, and mostly as a reference guide to Extended. It made sense back then.

Now it doesn't. Why are doing a separate manual for vanilla when we can just have vanilla's manual? Moreover, this has all the chances of being 1) not fully finished; 2) quickly abandoned if so and outdated...

I may sound harsh, but... sorry, I'm just saying what it is. This can still be around, of course, but as a museum piece, for those interested in web archeology, as extended is now an archeological piece of software.

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. I've been contributing to Pd's documentation for a few years now, and I can testify it doesn't hurt. I've written a whole new section on externals in Pd's manual and rewritten many help files. It's fine, it's possible.

And we should, as a community, pay attention to the fact that Pd has a manual, and that old, outdated and abandoned manuals of long gone Pd forks out there do not necessarily represent Pd's manual...

This is a big problem! There's a huge noise here. People are oblivious on what the actual and official Pd documentation is or exists. And the best solution for me to reduce the noise is to just simply REMOVE the noise...

So, yeah, puredata.info needs some attention for that matter too, as that's the website most people get to when checking pure data and I think it also points to FLOSS manual as being any relevant these days.

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...

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

Make it a safe and friendly area (for newcomers).

My 2 cents.

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.

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.