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

[Robert Poor]

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 at lists.cs.princeton.edu
> https://lists.cs.princeton.edu/mailman/listinfo/chuck-users

--:
Robert Poor
e:	robert.poor at 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.
--: