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

[Kassen]

Adam;

December 19th was an arbitrary date. How about we do the 16th since
> Tomasz can make that? I would really love a git expert around. If you
> guys haven't seen his tutorial on git with max, it is really
> wonderful.
>
>
I'm fine with anything. I'll have a friend over for much of December but
will make time for this. I might make him try on the tutorials as a
test-case :-)


> LaTeX has proven to be bad for many reasons. Asciidoc will be the new
> build system. I'll compile relevant documentation over the next few
> weeks so we can get going. The main benefit is that there is very
> little markup. So, if anyone has an idea all we will need is a plain
> text file or an email. It will be that simple to modify the
> documentation.
>


That sounds like a good match for my experience level with markup :-)


>
> Kas. Your response are quick and thoughtful. I can see why you
> disagree.


I don't think we actually disagreed, it was just the literal statement that
you made that I didn't feel was literally true. I took that opportunity to
point out in what ways the material that we need (nearly all of it exists in
some form or other) is scattered.


> For me the community has outgrown the current state of the
> manual. In the beginning when we were all digging our teeth in it was
> a great resource but now we hunger for more. I think for a beginner it
> still serves as a great reference but it needs more.
>
>
Absolutely. I think this is a sign of a larger phenomenon; the community is
"growing up" and people are trying more ambitious projects.  I also think
that's where the current set of issues with the type system come from. Those
bugs were probably there but previously we weren't extending classes,
passing them to functions, casting up and down a bit, then expecting the
result to fit into a array.

I am also thinking we need to split the manual into two major sections
> or possibly two documents, like Cycling 74 does. The max/msp manuals
> are incredible. The reference manual is just that while there is
> another manual for tutorials. Ours could be tutorials and code
> snippets. I haven't thought about this idea for too long but I thought
> I would see if it had any resonance.
>
>
I agree. In a way this is already the structure of the manual. To me a good
structure would be;

*Introduction (welcome and how to install ChucK at all)
*Basics
-how to make a beep
-flow control
-basic structures
(This stuff should cover enough to give a frame of reference for everything
else but not overwhelm)
*In depth consideration of topics
-concurrency
-what good are classes and functions
-events
-how does this UGen graph stuff work
-how to not hate MIDI (tricky subject :-) )
-etc.
(This stuff would basically document every major part in a friendly tone)
*Reference
-all UGens
-all operators
-all keywords
-all member functions
-etc
(Everything, and verified, but just the factual basics)

This is roughly the structure we already have, but the current manual has
some holes in it.

I have been looking through FLOSS manuals a bit. It might be a good
> place to have a scratch manual but I don't know about giving it all up
> to an outside source. Two issues for me: is there a way I can easily
> suck down the working version to include with the distribution and if
> we migrated to the site would Ge be cool with that?
>

Those are good questions. We also need Ge's call on on to what degree it
will be ok to grab useful bits from his thesis. That text does reserve all
rights while the manual to ChucK should probably have some sort of license
that is compatible with the major Linux distributions (because it would be
good to get packages in the future). I'm not sure what concerns play a role
there but let's find out before we run into issues later on.

I'd like to include at least the discussion of the structure of the VM in
the manual as that text -while mainly of interest to more experienced users-
is great for framing how it all fits together and *why* things are like they
are.


> Let's spend some time picking tools and then we will move forward. We
> should spend the day getting things done, not fighting with tech or
> intellectual property issues.
>
>
Yes. One option would be Google's new "wave" thing as well. I'm chiefly
suggesting that because I want to try it out. The WiKi is already there,
open to anyone, and we do know that it works for some things for some
people, unlike Wave. We also know that it tends to slowly become a mess if
not watched by somebody taking care of a page.

Another note; I bet that this push is going to unearth a slew of;
a) bugs.
b) things that may look like bugs and are instead features that are a bit
confused.
c) things that are certainly not bugs but simply labelled in the wrong way

Let's try to catch all of those in a centralised way as well to make the
most of our work and time.

ps. Kas, my thesis will become live once the final Ts are crossed. You
> may find some ChucK code in it ;)
>
>
In that case I would love to get a pdf in due time.

Yours,
Kas.
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.cs.princeton.edu/pipermail/chuck-users/attachments/20091128/b0353da6/attachment.htm>