[chuck-users] FLOSS (user editable) manual for ChucK

[Kassen]

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.
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.cs.princeton.edu/pipermail/chuck-users/attachments/20091217/524fa773/attachment-0001.html>