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.