On Sat, 5 Jun 2010, Dan Wilcox wrote:
Fair enough. My point was more that the writers should not forget who their intended audience is and should choose ease of writing over readability. The easiest solution from a writer standpoint could be that readers should refer to help in the source header files, but of course that's not practical ...
Sorry for the delay. I wrote most of the following a week ago but didn't finish the last few paragraphs... that's a long mail.
From a developer's standpoint, reading the source is not the same asdocumentation, because the source doesn't tell you what it's supposed to be doing, instead it tells you what it does.
I'm not sure what you mean about the headers... pd classes don't need to be declared with .h files, so most libraries don't have any.
There was some talk about picking up runtime info from classes, such that a documentation edition system could tell you things like : canvas is missing documentation for method "bounds" and it has four f-arguments. But it wouldn't work all of the time : e.g. for GridFlow, it would look like there is a single anything-method taking unlimited unchecked args. Same for all other cross-language interfaces that use class_addanything as little as possible.
You are right. Voting is not a good solution. However, neither is the position of "my format or the highway". However, I suppose it was a mistake to say that we should all have a graphical template to follow and to change all existing help files to it.
I believe in the separation of content and presentation. This has been a major transformation in the world of web since HTML4/CSS, and eventually took root deep into many web frameworks of the decade. It's not a web invention either. It was also deep in the SmallTalk 1980 GUI toolkit, where much of the inspiration came from. In Pd it's not really possible to do the separation, as coordinates are written all over the file format, but the least I can do is make it so that you don't have to position the objects yourself... most of the time.
If I was in your position, I wouldn't want to migrate without a good reason. After all, we all patch differently, we use PD because we love the freedom in how we can work.
It's not just for myself. I believe that the ideas I am putting forward for documentation, are essentially good for everybody.
One possible solution would be that we can at least agree upon what help patches should contain (argument lists, inlet/outlet descriptions etc) and not bother with exact format of "this text goes here, this canvas header is this big and this color, etc".
Let's bother about it, but let's bother about it separately. Layout and colours can go in abstractions where you can change the look of all helpfiles at once (to the extent that the automation has been done. in GridFlow it's perhaps 90% there). The first problem I see with not having a separation, is that people want to finish deciding the look so that they can start writing the docs because once you do it, it's really hard to change the look. That's why PDDP meetings introduced a receive-symbol for changing the colours ; but it didn't introduce abstractions, which are a much more powerful way to deal with the matter.
I remember making the point at PdCon07 that the help browser was confusing to use and I couldn't find the information I wanted (help, references) without going through each folder. A number of people gave me a dismissive look and I don't remember the responses I was given, but they were more along the lines of "it's all there, can't you see?". I got the feeling that since it wasn't a problem for those that had learned the locations of the objects and their names, then it wasn't a problem worth solving. That it was my fault and I should just read more. This did not and still does not sit well with me.
So, what were the solutions that you were proposing, or would have been proposing, or what are the elements of the problem that suggest what kind of solution it could be ?
As far as I know, the pd gui rewrite adds the ability for custom tcl/tk snippets through the command menu. This could be just a tcl call to svn diff.
Ok, so, you have to hunt all over the internet for pieces of tcl code that take 1k each ? Pd has this concept of externals, that are rather plug-and-play (or at least: can be), and then Pd-extended changed the deal and made it no-plug-just-play, and then Pd-devel ("gui-rewrite") would have those snippets of tcl floating around so that you can download your menu-items one by one ? A little bundling would help...
what's the "command menu" ?
Good point. If discussions are not public, we are not obligated to both share and defend our ideas or viewpoints.
Well, it's also that pdpedia is hard to defend. I expect pdpedia to be replaced by something else soon.
In doing so, one has to really give thought into what one is doing.
To give more thought into what one is doing, you need prototypes. Talking and thinking doesn't make one realise all the faults like a prototype does. Discussion better be built around prototypes than what-ifs.
To me, it's the difference between to stating an idea then coding it directly and stating an idea, researching it, presenting it others, getting feedback, and then coding it.
It's a good idea to think about the ability for a design to evolve. That way you can make a prototype early without feeling too guilty about it, and from the prototype you get much feedback that you wouldn't get from conversations, and then you can recycle the prototype into a more long-lasting solution (which would be why you wouldn't be guilty to code early, and why the design ought to be evolvable).
If we don't collaborate effectively, I feel we waste effort individually.
I've come to think of the default as being no collaboration at all, and look at effective collaboration as a form of saving. It's more positive and it conveniently removes the myth of a most perfect collaboration from the equation. The amount of waste is the distance between where we stand and the utmost bestest solution we can't even think of. Frustration doesn't come from this waste, it comes from measuring this waste. In the end, much of this waste doesn't even exist, or assumes unacceptable tradeoffs involving unstated requirements (or otherwise ignored requirements).
Also, we as a community look less active which, for an open source stand point, is not good.
Why would that be, according to you ? I mean why is the community looking less active... _ _ __ ___ _____ ________ _____________ _____________________ ... | Mathieu Bouchard, Montréal, Québec. téléphone: +1.514.383.3801
_______________________________________________ Pd-list@iem.at mailing list UNSUBSCRIBE and account-management -> http://lists.puredata.info/listinfo/pd-list
