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

@whale-av said:

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.

@MikeMorenoDSP said:

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.

@60hz said:

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

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

@porres "but are you counting the help files of dozens of libraries it had?"
No, the extended doc only referenced the vanilla objects.
Help for externals was contained within their folders in the relevant "extra" folders..... hence the problems people sometimes have with missing help files for external single binaries.

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.

@whale-av said:

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.

@whale-av That looks to be it. Odd that google does not seem to find it and every website I found with a link to a floss manual was the other one. Floss also took the link off of the write.flossmanuals.net website to the main page so I did not find it by clicking through the links from there, should have actually read the URL. Thanks.

@porres Yes a companion to the help file. Maybe as a .pd file and online too.
Like this:
https://docs.cycling74.com/max8/refpages/oscbank~

@whale-av said:

@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/

Regarding the discussion of Floss being part of the documentation, I believe so. But only in the way about update puredata.info. Which requires a survey of these unofficial documentation to be listed on the official website.

Another possible reference is http://www.cooperbaker.com/home/code/pd spectral toolkit/

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

I think the right-click object menu can be a very useful feature especially for beginners. Perhaps it can be done with a tcl plugin to be installed via deken and documented in a specific introduction for first users. So they would already be familiar with using externals in some way.

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

@emviveros Yup, guess orange not yellow, same as the pdf which David linked and seems to be the same as http://write.flossmanuals.net/pure-data/introduction2/ but the Dataflow->Math link works. I have not compared them in depth but a quick comparison of a few sections suggests them to be the same. I am guessing when the orange sidebar version went to pdf a new working version was opened for expansion but was never expanded.

@oid I can see the importance of Pd Floss stay updated, but I don't mind how to access it to edit. I'm asking a friend which make the portuguese translation, but I don't know anything new right now.

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.

Well, the Floss manual is a very very old and totally unofficial documentatin, made by a third party, and that mostly documents how to install and use Pd Extended 0.39...

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.

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.