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

[Tomasz Kaye's brain]

@kassen
"[bugs] Let's try to catch all of those in a centralised way as well
to make the most of our work and time."

Yes. That reminds me (slightly OT) , would it not be a good idea that
a issue tracking system was used for ChucK? This is up to the devs
ultimately, but i think there must be some good free options around
and i can image it would make things easier (both for reporting and
for fixing).

2009/11/28 Kassen <signal.automatique at gmail.com>:
> 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.
>
> _______________________________________________
> chuck-users mailing list
> chuck-users at lists.cs.princeton.edu
> https://lists.cs.princeton.edu/mailman/listinfo/chuck-users
>
>