Kas: Your comments underscore the need to create a ChucK _reference manual_, even before creating a _programmers guide_ . By definition, most ChucK users are already programmers for whom explanations of object oriented programming, inheritance and type casting is superfluous. On the other hand, being able to quickly learn the syntax for oo, inheritance and type casting is important. Give me a decent ChucK reference manual (i.e. what the heck does the reserved "pure" keyword do?), and I'll be happy to write a few tutorials for beginners. - Rob On 17 Dec 2009, at 07:24, Kassen wrote:
Adam;
Wise words again Kas.
Thanks.
I support your sentiment about making the docs clear to a teenager but we have to stay true to the information. The nice thing about the new system is that we can try it and if we don't like it we just roll back the version and no harm is done.
Agree. I was specifically referring to the fist sentence of the section on array;
Arrays are used represent N-dimensional ordered sets of data (of the same type).
This is completely true, but I'd say that much of our audience will already know what arrays are (in which case they will gloss over it as it's not new) or they don't in which case we have a good chance of their eyes glossing over at this. I'm not sure about other countries but in NL you only get set theory if you pick a certain kind of math at a certain level of highschool, which is to say nothing about "N-dimensional". Both aspects of arrays should be in the text but I'm willing to bet I could find you a dozen people who would be interested in making their own sounds and programs who couldn't tell you what this sentence means while being perfectly capable of getting up to speed with arrays in 1o minutes.
I know this line was likely put there by somebody with lots of experience in teaching, CS and music and that I as a independent artist with just a few workshops under his belt in teaching experience am on thin ice here but I have serious doubts about opening a important section with a sentence like that.
I think we may include a section of books to read to bring someone up to speed on the concepts.
Sure, and perhaps a brief lexicon of terms like "harmonics" and "inheritance".
You may have noticed that instead of doing a full tour of Windows the front of the manual gives links to a screen tour to get started with ChucK. We could do the dsp math version of that.
I liked that. I bolted on the text by Kijjaz to cover the essentials of Linux compilation to at least get started there on the most prominent platforms. There is a lot of room to improve there too.
For a teenager we may just want to included more examples as well. I would like to start putting all of the code inline in the documentation. I am also dreaming of the day when every ugen gets an example. Maybe also the Standard Libraries. The examples will address your concerns about being clear about what all the language features are good for.
Yes. And I'd like to make sure we explicitly cover what all of the Std functions abbreviate, that should already help make them more clear.
I like your ideas about including Smirk. I think we also need to include the chuck shell, and then a brief tutorial or disciption on the miniaudicle. Maybe audicle too, though my understanding is that it isn't used very much.
The problem with the Audicle is that if you'd try to use it now with a updated manual you will be missing a lot of functionality as the included vm is rather old. I think it'd mention it in glancing now. The mini on the other hand will save people from the "scary" terminal which I found adds a lot of value for a lot of people in the beginning.
Yours, Kas. _______________________________________________ chuck-users mailing list chuck-users@lists.cs.princeton.edu https://lists.cs.princeton.edu/mailman/listinfo/chuck-users
--: Robert Poor e: robert.poor@nbt-ventures.com p: +1 617 818 5115 b: http://blog.nbt-ventures.com --: This message and the information it contains are the proprietary and confidential property of NBT Ventures and may be privileged. If you are not the intended recipient, please do not read, copy, disclose or distribute its contents to any party, and notify the sender immediately. --: