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

As a Puredata teacher in a fine art school since 10years (and many workshops in China) the only solution for me to make pd "usable" by my students, was to distributed my own puredata version modified with translated help files from an "computer-scientist" to an "artist" point of view, and with many extra things.

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

@60hz , I know @whale-av already mentioned it but here is the wiki in progress @beem and I have created with wikidot:
http://puredatabase.wikidot.com/

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?

@MikeMorenoDSP said:

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

@60hz said:

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.

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