I think there is a huge need for exactly something like what Derek mentions--a reference manual. I don't have the internet at home, and when I'm planning something like writing a program, my first step is to use pencil and paper, and sketch out the parts of my design, and try to decide the most logical way to build and test my application. A real reference encyclopedia would make this task MUCH easier. It's not a task that PD really lends itself too, as I tend to get all mucked up, if I didn't figure out the answer on paper first. For me, the computer screen makes it too easy to just start patching away without a clear idea of the logic I need.

However, I think there is a strong need for a manual in another area, and that is overall program design and application building in Pure Data. What different ways are there to conceptualize a Pure Data application? What approaches can one take in application design? What decisions should be made in advance? How can one do object-oriented PD (there are at least some parallels), and how might that differ from other approaches? What are pitfalls to avoid? What are typical problems that one can expect to encounter, including problems relating to different platforms and limitations of PD, and what are good strategies to overcome these limitations? What are different ways to do GUI and control, and to seperate the GUI from the rest of the patch? How to optimize a patch, or reduce CPU load on a hungry patch? How can you do testing, to see if your idea is even feasible with a given set of CPU resources?

At the very least, a thorough FAQ is essential. But even better, a manual that has an FAQ index pointing to the answers in context. Remember, some people coming to PD, don't have real programming experience. So teaching some programming concepts might be helpful--I myself don't totally know the best way to work on large scale design in PD. I mostly learned programming on my own, so I'm definitely lacking in ideas about how bigger programming projects are organized. I don't even know what philosophies exist (extreme programming I've heard of, but I'm sure there's many more.)

THESE are the questions that I currently don't see being addressed, except ad hoc in email exchanges on the list. They are, I would suggest, appropriate to a "manual" on PD programming, as it's not just a matter of how a particluar object works, but would include insights gained from the real world of programming. And honestly, when I open up PD, I'm most likely working on a particular patch or problem. I want to have my reference material open next to me. I don't want to search through someone's tutorial patches for the answer to one specific problem, especially if its a more general philosophy/design question, rather than a question about a specific object.

If such a manual existed, alongside a reference manual of all the objects and their inputs and outputs, I think PD would have great potential to grow its user base.

Just remember this: If I'm considering using a new programming language or new musical software, the first thing I do is browse the website and look at the manual. If the manual looks good, I'm FAR more likely to give the language a serious try. This is part of the reason why I didn't try PD at all for a year after I first considered using it! To give another example, I started programming in ChucK recently, partly because it has a simple, nicely written manual (plus it's 10x quicker to develop some things, like granular synthesis, than PD, and it has the working STK stuff that I can't seem to get for PD Windows.) Reading the manual a couple of times convinced me that it would do some interesting things and was worth a try. I'm sure that I'm not the only user out there that approaches things in this way. Accessible documentation is important -- and by accessible, I mean accessible outside of the program in question.

~David

On 4/25/06, derek holzer <der...@x-i.net> wrote: