Adam; Great to see you here. Yes, isn't it? I was enjoying Tomasz's posts elsewhere for a few years now before running into him at Steim. It's a small world.

Firstly, I would like to announce to you all that I successfully defended my PhD this week and now that is done I will be spending more time here collecting the great ideas that come through this list.

Both are great news! congratulations! What is your PhD on?

Presently I am working on converting the manual to asciidoc, which is a simple formatting language that produces both html and pdf copies. This will allow us to keep the manual and the website in sync. This has been a sore point for a long time now.

Right, this is a good point. The threshold of entry should be lower there so everyone who would like to help can. I think most of the more senior users have their own field of expertise that many others will know less about and of course new users will see issues that the rest overlooks. To me the manual is a important thing as it will be the first port of call for many people who are considering ChucK; that's also why I felt the recent compilation issues needed a quick fix. If we don't make a good first impression we'll never reach world-domination.

I have signed up for a github account and I would be happy to put the chuck manual there. This will allow everyone to grab from my branch and then I can pull changes from everyone and then commit them back to the project. How does that sound?

Good. But then we need a intro to this. A intro to using this system aimed at people who are not routinely using version management. Like me :-).

Future. I want to have a documentation sprint. How does December 19th look? Anyone else interested? I would be online all day giving out tasks and helping people get into the technical parts of adding to our document and also looking for snippets of wisdom or errata to improve the minutia.

This sounds like a good idea, and very fitting with the inspiration Tomasz here took from the recent Ardour sprint in Rotterdam and online. Let me commit to covering the interaction between DSP in code and in UGens; that's a interesting topic that I feel has so far been under-appreciated even though it's one of the things where ChucK can really shine as compared to other systems. I think that too much fragmentation of the project is not good. Ge has

done a great job and keeping everything together and I think that is one of the reasons we have so many people here. It is easy to find information (or to find out that the information doesn't exist) and it is easy to ask questions to a list that actually responds. Having a dev or working version of the docs is good but having it all in one place for newbies definitely eases the transition, so I don't want to break that "feature."

I respectfully disagree there. I do agree that Ge is doing a amazing job that can't be praised highly enough but the information is not all in one place. Most is in the manual but then some things are only in the examples or even just mentioned in Ge's thesis (whole chunks of that should likely be pasted straight into the manual). Then there are things that are only mentioned in the list archives or on the forum or WiKi, hinted at in the old docs on the site or even just in the VERSIONS file. I think there are also bits that aren't documented at all; there must be as every once in a while something pops up that has been implemented but never documented. Of course this has so far not been a great issue as the scene is still small enough for the people who know how to find it all to answer all questions and this can certainly be attributed to Ge who set the tone of friendly help to all comers (quite unlike some lists I hear about). To pick just one thing; just the other day I was talking about the "repeat" structure in ChucK on the Toplap list when debating the influence of syntax on musical movements (as well as kissing as a quantitative measurement of musical quality; it's a wonderful list). Even I myself can't remember where I found that one (might be Ge's thesis?). The manual mentions it's existence, but not how it works; repeat(3) { <<<"this will be printed three times">>>; } ...a wonderful device, it can be used immediately even if you have just seen it once so it's a great introduction to loops, it's simplicity makes it great for casual impulsive livecoding with a drink at hand, but don't ask me where it's documented. These are my current thoughts. What do you think?

Yes, yes, yes &yes. Great ideas, it's good to see you back on the case and we'll do this. I'm in and I hope we'll see a strong turnout of people writing, suggesting and proof-reading. After this I'd like a sprint on the /examples/ dir. There are some bits in there that I find questionable. We can debate style (some structures have become out-dated) but I feel they should all run without errors or warnings (this is not currently the case) and there are some otherwise dubious bits here and there. I think I kept some notes on those somewhere but might have misplaced them. Great initiative! Kas.

Hi Adam, thanks for the reply.

Second, the manual is open source and I strongly encourage editing but it is currently only available through CVS and it is formatted via LaTeX. This has been a major barrier for getting collaborators.

LaTeX is really neat, but it is a hard sell!

I have signed up for a github account and I would be happy to put the chuck manual there. This will allow everyone to grab from my branch and then I can pull changes from everyone and then commit them back to the project. How does that sound?

Perhaps responders to this thread can indicate if they have experience working with git or other similar scm, to gauge how much of a barrier this might be. I'm comfortable working with git. But i wonder how many other chuckists are used to scm systems. I underestimated the difficulty with which new users can get to grips with a scm system; A few months back i tried to encourage the max/msp using monome community to adopt git (and github) to avoid the fragmentation i was seeing with many different versions of monome apps. I posted a tutorial on how to use git for max, evangelised about the benefits, but for whatever reason it didn't work out. I think this was because for most people the tech barrier with git (or any scm) was too high. I think chuck users are more likely to be used to a scm system already, but if i were choosing how to publish editable ChucK documentation, i think i'd still choose for a web based editing system like FLOSS manuals, because it'd be a shame to have technology get in the way of people feeling as though they can contribute.

I want to have a documentation sprint. How does December 19th look? Anyone else interested?

Damn!, i'm very much interested but I'll be away from computers between the 17 and 21st of december

Hey All, This discussion is very encouraging. I have long hoped for a few more eyes when writing the docs and not after I have moved on to other projects. 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. 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. Kas. Your response are quick and thoughtful. I can see why you disagree. 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. I also agree with you that the next major place to fix up is the examples directory. 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 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? We have a wiki. I would be more interested in reinvigorating that space for this project. Maybe we could decide at the end of the sprint that we have outgrown it but I would like to make sure that is the answer before committing to hard to another site. 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. --art ps. Kas, my thesis will become live once the final Ts are crossed. You may find some ChucK code in it ;) 2009/11/27 Kassen :

Tomasz;

...

Perhaps responders to this thread can indicate if they have experience working with git or other similar scm, to gauge how much of a barrier this might be.

Sadly none. I'm up for anything as long as there are some pointers and a assurance that i can't break anything.

...

I'm comfortable working with git. But i wonder how many other chuckists are used to scm systems. I underestimated the difficulty with which new users can get to grips with a scm system; A few months back i tried to encourage the max/msp using monome community to adopt git (and github) to avoid the fragmentation i was seeing with many different versions of monome apps. I posted a tutorial on how to use git for max, evangelised about the benefits, but for whatever reason it didn't work out. I think this was because for most people the tech barrier with git (or any scm) was too high.

Ok. So we need some info on why this is a good idea here and how to use it for this purpose. It'd be especially good if it were fun and easy as well.

If need be we may need to add a wiki page, or simple list posts to this. I suspect there are quie a few lurkers here, people who have questions they feel might be silly, and that's exactly the kind of person who could make a very important contribution here so I feel we should try to make that sort of thing as easy as possible.

There is more to manuals that the letter of the text anyway so we may need more layers than just a method to add text; questions might be at least as valuable in this case. In my earlier post I took a subject I'd like to write on just because I had questions on that before myself... but maybe this isn't a topic that a lot of people are fighting with. Maybe MIDI-out is much more important to a more people; I have some gut-feelings but I don't know for sure.

...

I think chuck users are more likely to be used to a scm system already, but if i were choosing how to publish editable ChucK documentation, i think i'd still choose for a web based editing system like FLOSS manuals, because it'd be a shame to have technology get in the way of people feeling as though they can contribute.

I could see how that would help, yes. Is this practical on Adam's end at all? What systems are there and can we get those installed somewhere?

Kas.

_______________________________________________ chuck-users mailing list chuck-users@lists.cs.princeton.edu https://lists.cs.princeton.edu/mailman/listinfo/chuck-users

@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 :

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

Adam Tindale wrote:

Upon further investigation there are a few other downsides to FLOSS manuals: ...

The most important feature for me would be support for ChucK source code snippets. The wiki is completely broken in this regard -- each line of code must start with a space character for some odd reason. The source code snippets should also be importable from runnable bits of source code, say the examples directory, not inlined directly into the documentation. This way it is easy to keep all the source code in the docs up-to-date, making sure they run properly with each new version of ChucK. michael

Good points Adam. A couple of related comments: On Sat, Nov 28, 2009 at 8:22 PM, Adam Tindale wrote:

Upon further investigation there are a few other downsides to FLOSS manuals:  There is no provision for sections, just chapters

Judging from the existing manuals (looking at the bypassing internet censorship one as an example), although the chapter is the main unit, it looks like subheadings are taken into account too, at least when generating PDF indexes.

 The document is created with HTML so layout possibilities are limited not only by that markup but what the site is able to translate to PDF

True. It may not be possible to get a 1-to-1 formatting transfer from how the current manual is.

 The PDFs don't look very good. CSS editing is possible but that would probably require one person doing that for most of the day

Although the initial styling work would be a pain, it might only be necessary to do it once. I'm sure I'm not the only one here, but I'm fairly handy with CSS (though I'm no designer or typesetter) and wouldn't mind smartening it up with some rules in case better qualified users aren't available.

 The filenames of the downloaded items seems to be fixed to something I don't like

Yeah the filenames of the exported PDFs are ugly, and non-descriptive, which is a shame. Of course the exports that are destined for distribution would get renamed.

 The file sizes of the PDFs are huge

The internet censorship manual is around 8Mb, but I noticed it has lots of images, which I imagine are making it heavier.

 Making a title page doesn't seem as easy as it should be

Agreed.

It will take some time to get our current manual into their site to start changing it

Yes. Perhaps this could go relatively quickly if its a task we could split among several people.

December 16th is in my calendar, is it in yours?

It is.

Michael - excellent suggestion. FLOSS Manuals seems to have a facility for including code easily. Has anyone tried putting ChucK code in to see if it barfs on it? I think google wave would be confusing. FLOSS manuals has a chat function and also the ability to make talk pages that aren't published in the manual. That way we can make a list of ideas or errata and it will not be included when a user downloads the pdf. The final pdf produced by this will be included in the ChucK distribution. I am happy to manage that migration when new versions of either ChucK or the manual are released. Scott - I am glad the manual was a friend at the bar. I took a computer to the bar many times when learning ChucK and got many strange looks when people looked at my screen. They all assumed I was trying to steal their banking information. Tomasz - I was referring to sections as being farther up the layout tree than chapters. There are sections and subsections of chapters that seem to do quite well in FLOSS manuals. What I am looking for is a way to make a split in the manual between our tutorials and the reference section. It isn't a pressing issue. So, it looks like we have some CSS people who can look at the issues here. FLOSS manuals looks terrible. Fortunately we have full access to the CSS. I would love if someone were to spend some time with this during the Christmas break. I know that Ge spent some time tweaking the website layout. I wouldn't want to throw away too much of that work. The colours and general typesetting make reading the ChucK reference webpages very easy on the eyes. The more I think about it the more I am strongly leaning towards FLOSS manuals. The group we have assembled will work most efficiently that way. If we migrate away from this after the sprint then that is ok, but I would like to get as many people involved as possible to start out. Can we make a final decision by the end of this week? If we can then I will start migrating the manual to the site. Other collaboration possibilities: We use Wave or some sort of chat to talk to each other while we use some other method for building the docs. Right now they are in LaTeX and we could go with that system. I would be happy to accept changes and ideas all day and then just put them into the current system. We could also use asciidoc. It is a great little documentation system that has easy markup that easily compiles a pdf or generates a website. This would allow us to keep our current site architecture. If we go with either of these solutions (or another build system) then we will need svn or git to manage the files and collaborations. Although I see building the docs ourselves as a superior system, I see the layers of tutorials we will need to do to get people up to speed. That is a major downer. These are my current sleepy thoughts. --art On Tue, Dec 1, 2009 at 7:15 PM, Scott Hewitt wrote:

Hi,

Perhaps we could all work on the wiki or in google wave (I have a few invites if people need them) and then once the content is done work out the presentation side.

The pdf manual is a great resource and the easy of turning it into a physical object is great, I actually took my paper copy to the pub for a few nights when I first started chuck.

However good documentation in my mind would also have a role online as part of the wiki and maybe eventually as an integrated help system perhaps within the miniAudicle.

So I would suggest that we aim to create / update the content of the manual in a way which is as flexible as possible going forward.

just my two cents :)

scott

On Sat, Nov 28, 2009 at 9:13 PM, Tomasz Kaye's brain wrote:

...

Good points Adam. A couple of related comments:

On Sat, Nov 28, 2009 at 8:22 PM, Adam Tindale wrote:

...

Upon further investigation there are a few other downsides to FLOSS manuals:  There is no provision for sections, just chapters

Judging from the existing manuals (looking at the bypassing internet censorship one as an example), although the chapter is the main unit, it looks like subheadings are taken into account too, at least when generating PDF indexes.

...

 The document is created with HTML so layout possibilities are limited not only by that markup but what the site is able to translate to PDF

True. It may not be possible to get a 1-to-1 formatting transfer from how the current manual is.

...

 The PDFs don't look very good. CSS editing is possible but that would probably require one person doing that for most of the day

Although the initial styling work would be a pain, it might only be necessary to do it once. I'm sure I'm not the only one here, but I'm fairly handy with CSS (though I'm no designer or typesetter) and wouldn't mind smartening it up with some rules in case better qualified users aren't available.

...

 The filenames of the downloaded items seems to be fixed to something I don't like

Yeah the filenames of the exported PDFs are ugly, and non-descriptive, which is a shame. Of course the exports that are destined for distribution would get renamed.

...

 The file sizes of the PDFs are huge

The internet censorship manual is around 8Mb, but I noticed it has lots of images, which I imagine are making it heavier.

...

 Making a title page doesn't seem as easy as it should be

Agreed.

...

It will take some time to get our current manual into their site to start changing it

Yes. Perhaps this could go relatively quickly if its a task we could split among several people.

...

December 16th is in my calendar, is it in yours?

It is. _______________________________________________ chuck-users mailing list chuck-users@lists.cs.princeton.edu https://lists.cs.princeton.edu/mailman/listinfo/chuck-users

_______________________________________________ chuck-users mailing list chuck-users@lists.cs.princeton.edu https://lists.cs.princeton.edu/mailman/listinfo/chuck-users

Tomasz Kaye's brain :

...

Michael - excellent suggestion. FLOSS Manuals seems to have a facility for including code easily. Has anyone tried putting ChucK code in to see if it barfs on it?

... I entered some ChucK code into a <pre> element. That seemed to work fine in the preview. Though probably needs more testing (for instance, do long lines inside a <pre> element automatically wrap in PDF export? my suspicion is that they might not).

Does FLOSS manuals have an import mechanism? This would be essential for keeping the ChucK examples/snippets separate from the documentation itself. For instance, in APT documentation format http://maven.apache.org/doxia/references/apt-format.html there is a snippet macro http://maven.apache.org/doxia/macros/index.html#Snippet_Macro michael

Currently the examples are hard coded in. This has problems, as we all know, but it is the best system we have for now. I am not too worried about it. I have a vision... Does everyone know the Max/MSP manuals? They are amazing. I have a dream that every UGEN has a page or two to itself where all the inputs and outputs are explained and there is a UGEN specific example in the docs that makes it clear how the features work. I know we can do this! I would love to get a start on it during the sprint. Even if we documented the .sync feature of UGENs more I would be happy with that as a start. FLOSS manuals has started a page for us. It looks like the system for us. They have an API for putting the manual to print and giving more control. It is a bit young but I think we can do some feature requests and have it grow with us. I will start preparing the manual for upload and start roughing it on their site. --art 2009/12/2 Tomasz Kaye's brain :

@Michael: I'm pretty confident that FLOSS Manuals doesn't have such a dynamic code importing capability, or support for variables or dynamic substitutions in general. So with FLOSS, code snippets would be 'hard coded' into the documentation (I assumed that it was currently this way with the LaTeX docs too, is that right Adam?).

On Wed, Dec 2, 2009 at 4:43 PM, Michael Heuer wrote:

...

Tomasz Kaye's brain :

...

...

Michael - excellent suggestion. FLOSS Manuals seems to have a facility for including code easily. Has anyone tried putting ChucK code in to see if it barfs on it?

... I entered some ChucK code into a <pre> element. That seemed to work fine in the preview. Though probably needs more testing (for instance, do long lines inside a <pre> element automatically wrap in PDF export? my suspicion is that they might not).

Does FLOSS manuals have an import mechanism?  This would be essential for keeping the ChucK examples/snippets separate from the documentation itself.

For instance, in APT documentation format

http://maven.apache.org/doxia/references/apt-format.html

there is a snippet macro

http://maven.apache.org/doxia/macros/index.html#Snippet_Macro

  michael _______________________________________________ chuck-users mailing list chuck-users@lists.cs.princeton.edu https://lists.cs.princeton.edu/mailman/listinfo/chuck-users

_______________________________________________ chuck-users mailing list chuck-users@lists.cs.princeton.edu https://lists.cs.princeton.edu/mailman/listinfo/chuck-users

Ok All, We are moving to FLOSS manuals. Over the next week I will start to prepare the manual for this format and start roughing it in. As this happens I will update the list on links and processes. I will gather some documentation about FLOSS manuals so you can read a bit or maybe hack around on the site before the sprint. We will run this experiment and see how it goes. Hopefully this will prove to be a sustainable documentation practice and an easy migration. Thanks for all input. This has been a fruitful discussion. a 2009/12/4 Tomasz Kaye's brain :

@adam

Yes, agreed about the Max/MSP docs. The best i've come across for synthesis software. Extended UGen documentation with examples would be excellent.

Looking forward to helping out with the FLOSS manuals stuff. Thanks for your work!

On Thu, Dec 3, 2009 at 7:17 PM, Adam Tindale wrote:

...

Currently the examples are hard coded in. This has problems, as we all know, but it is the best system we have for now. I am not too worried about it. I have a vision...

Does everyone know the Max/MSP manuals? They are amazing. I have a dream that every UGEN has a page or two to itself where all the inputs and outputs are explained and there is a UGEN specific example in the docs that makes it clear how the features work. I know we can do this! I would love to get a start on it during the sprint. Even if we documented the .sync feature of UGENs more I would be happy with that as a start.

FLOSS manuals has started a page for us. It looks like the system for us. They have an API for putting the manual to print and giving more control. It is a bit young but I think we can do some feature requests and have it grow with us.

I will start preparing the manual for upload and start roughing it on their site.

--art

2009/12/2 Tomasz Kaye's brain :

...

@Michael: I'm pretty confident that FLOSS Manuals doesn't have such a dynamic code importing capability, or support for variables or dynamic substitutions in general. So with FLOSS, code snippets would be 'hard coded' into the documentation (I assumed that it was currently this way with the LaTeX docs too, is that right Adam?).

On Wed, Dec 2, 2009 at 4:43 PM, Michael Heuer wrote:

...

Tomasz Kaye's brain :

...

...

Michael - excellent suggestion. FLOSS Manuals seems to have a facility for including code easily. Has anyone tried putting ChucK code in to see if it barfs on it?

... I entered some ChucK code into a <pre> element. That seemed to work fine in the preview. Though probably needs more testing (for instance, do long lines inside a <pre> element automatically wrap in PDF export? my suspicion is that they might not).

Does FLOSS manuals have an import mechanism?  This would be essential for keeping the ChucK examples/snippets separate from the documentation itself.

For instance, in APT documentation format

http://maven.apache.org/doxia/references/apt-format.html

there is a snippet macro

http://maven.apache.org/doxia/macros/index.html#Snippet_Macro

  michael _______________________________________________ chuck-users mailing list chuck-users@lists.cs.princeton.edu https://lists.cs.princeton.edu/mailman/listinfo/chuck-users

_______________________________________________ chuck-users mailing list chuck-users@lists.cs.princeton.edu https://lists.cs.princeton.edu/mailman/listinfo/chuck-users

_______________________________________________ chuck-users mailing list chuck-users@lists.cs.princeton.edu https://lists.cs.princeton.edu/mailman/listinfo/chuck-users

_______________________________________________ chuck-users mailing list chuck-users@lists.cs.princeton.edu https://lists.cs.princeton.edu/mailman/listinfo/chuck-users

i'd be happy to write some on LiSa, but i'd also love some help, especially from you; i clearly only use and understand a fraction of what LiSa is useful for! dt On Dec 5, 2009, at 5:50 AM, Kassen wrote:

Will Dan himself cover LiSa? A whole volume could be written on LiSa...

I like the idea of providing some examples of ways that LiSa can be used. For instance, I was wondering about the potential (and suitablility) of the LiSa UGen as a way of recording and playing back automation data (for driving params of other UGens), rather than for audio. Have any of you used it in that way? 2009/12/5 Kassen

2009/12/5 dan trueman

...

i'd be happy to write some on LiSa, but i'd also love some help, especially from you; i clearly only use and understand a fraction of what LiSa is useful for!

:-)

I do still have a skeleton for a LiSa-based convolution reverb lying around somewhere. I seem to remember it's something like 25 lines (I scary stuff). I'd like to also do a flanger and iir lowpass filter (I'm fairly certain both can be done)...

There are two downsides to that though; I think that when taken to the extreme people will wonder what the rest of ChucK is good for and I also think that the manual should be accessible, not a leading cause for insanity in computer musicians.

Mostly kidding. Ok, I do think that such examples could be useful in that creative LiSa-usage does potentially cover a lot of important aspects of more serious DSP without breaking the cpu-bank like a .last() to a sporked shred to a Step would. I also think that so far the docs and examples haven't yet covered how we can do that sort of thing in ways that would cause some serious issues for SC or Max. We're paying for not block-precessing (with purring cpu-fans) so we should probably show what that's actually good for.

Yours, Kas.

_______________________________________________ chuck-users mailing list chuck-users@lists.cs.princeton.edu https://lists.cs.princeton.edu/mailman/listinfo/chuck-users

What's the plan for the sprint tomorrow? Will it first be a question of just recreating the existing manual on the FLOSS site? If so it might be good to agree in advance on how certain entities should be transalated across. Or a chapter can be designated as an example, that we can use as a guide for consistency. Maybe you had thoughts about this already Adam? About time zones: I'm in GMT+1. The FLOSS chat works well i think, for coordinating stuff while we're busy working on it. 2009/12/5 Kassen

Tomasz;

...

I like the idea of providing some examples of ways that LiSa can be used.

There are already quite a few in /examples/special.

...

For instance, I was wondering about the potential (and suitablility) of the LiSa UGen as a way of recording and playing back automation data (for driving params of other UGens), rather than for audio. Have any of you used it in that way?

That does make perfect sense to me, especially if there is some specific curve you want to use regularly that might be computationally expensive to generate; you should be able to calculate it once, store it in a LiSa, the re-use it many times.

Don't underestimate the combination of Envelope and the various Gen UGens though. I think that's more powerful for this application in the general case.

_______________________________________________ chuck-users mailing list chuck-users@lists.cs.princeton.edu https://lists.cs.princeton.edu/mailman/listinfo/chuck-users

This will be an ongoing effort, correct? I'm not sure how much time I'll have tomorrow to help out. It's very important and I want to help with documentation. Mike 2009/12/15 Kassen

2009/12/15 Tomasz Kaye's brain

What's the plan for the sprint tomorrow?

...

I'd like to know about this as well. I reserved all of tomorrow for this (aside from breaks for food and I'll need half a hour for a brief meeting). I'd be happy to apply my time and expertise wherever Adam feels they are applied best. If I don't hear anything I'm going to write about the interaction between code and UGens and make sure the UGen reference is complete. If there is time left I'd also get started at making sure all UGens have a simple example dedicated to them. I'd like to make those as simple as possible while making sure they all have at least some musical appeal.

Those are things that I know something about and that would be fun to write as well as useful.

I'd be happy to continue editing after the sprint (as time and inclination permit); it's probably a more efficient usage of my time to write things there once than to help with issues on the forum or list.

I'd also like to hear from the DEV's on this initiative. Some areas may not warrant writeups now as they might have changes in cvs already (making it better to postpone documentation), and as (most of?) the DEV's also teach they should be aware of what areas lead to most questions in classroom situations and so may warrant special attention.

Yours, Kas.

_______________________________________________ chuck-users mailing list chuck-users@lists.cs.princeton.edu https://lists.cs.princeton.edu/mailman/listinfo/chuck-users

-- http://michaelclemow.com http://semiotech.org

Scott; Whats happening?

A search for "chuck" on flossmanuals yielded no results, I think I'll start using our own wiki tomorrow (well, today, in this time-zone) unless someting more concrete pops up. I suggest that if we don't hear from Adam (he may be dealing with unforseen situations) we all just create explanations and documentation in any area we see fit to the best of our abilities. The text is the most important thing after all; if just five people each write a piece on one area that was previously lacking I think that should already be a signifficant improvement. This initiative is getting quite "distributed" right now, with Adam apparently offline and no word from the DEV's but I don't think that need be a huge issue as it seems like most ChucKists have their own favourite areas and specialities anyway. After some sleep I'll keep my GMail chat as well as wave open in case anyone needs me, I'm also up for using any chat protocol that can be conveniently used from Linux. We could simply use the list as well. Yours, Kas.

Hey Guys, I lied. The sandbox is here: http://en.flossmanuals.net/bin/view/ChucK I'll start putting up the sections later tonight. --art On Tue, Dec 15, 2009 at 5:56 PM, Adam Tindale wrote:

Hey Guys,

There is a space reserved for us at flossmanuals.net/bin/chuck

I am pulling the manual apart tonight so that it will be ready to hack through tomorrow. I plan to be online from 9-5 MST.

For tomorrow please sign up for an account. We can start by using the mailing list to get coordinated with our user names and then transition to the chat function in Flossmanuals.

This is going to be fun. I think we should look at how easy it is to collaborate and maybe work towards improving the documentation in the UGEN section and compile a list of other issues and see how many of them we can solve quickly.

Thanks for all the help!

--art

2009/12/15 Kassen :

...

Scott;

...

Whats happening?

A search for "chuck" on flossmanuals yielded no results, I think I'll start using our own wiki tomorrow (well, today, in this time-zone) unless someting more concrete pops up. I suggest that if we don't hear from Adam (he may be dealing with unforseen situations) we all just create explanations and documentation in any area we see fit to the best of our abilities. The text is the most important thing after all; if just five people each write a piece on one area that was previously lacking I think that should already be a signifficant improvement.

This initiative is getting quite "distributed" right now, with Adam apparently offline and no word from the DEV's but I don't think that need be a huge issue as it seems like most ChucKists have their own favourite areas and specialities anyway. After some sleep I'll keep my GMail chat as well as wave open in case anyone needs me, I'm also up for using any chat protocol that can be conveniently used from Linux. We could simply use the list as well.

Yours, Kas. _______________________________________________ chuck-users mailing list chuck-users@lists.cs.princeton.edu https://lists.cs.princeton.edu/mailman/listinfo/chuck-users

Hi All, I have pulled apart the manual. I have put all the bits online here: http://creativefootwork.com/chuck/ You will find the text files of different parts of the manual and then some images and example patches. We will need to stitch these back together. I have made a quick start putting it on Floss manuals. I am going to head to sleep but if anyone wants to continue where I left off the materials are there. Kas, great suggestions. Let's do as many of them as we can tomorrow. There are some talk pages we can use to keep these ideas inline with the documentation. This has been an issue in the past. --art

So far I'm finding it most efficient to paste from the source docs directly into the FLOSS editor's html view, and manually take care of creating paragraph tags, pre tags etc. (I found that pasting stuff into the WYSIWYG view results in lots of html crud, mainly br tags, that then have to be cleaned out later.) On Wed, Dec 16, 2009 at 9:20 AM, Tomasz Kaye's brain

wrote:

Great. I've made a start recreating the installation chapter. It'll be a straight copy of the pdf version as far as possible. Username is: TomaszKaye. Speak to you on the FLOSS chat.

On Wed, Dec 16, 2009 at 6:47 AM, Adam Tindale wrote:

...

Hi All,

I have pulled apart the manual. I have put all the bits online here:

http://creativefootwork.com/chuck/

You will find the text files of different parts of the manual and then some images and example patches. We will need to stitch these back together. I have made a quick start putting it on Floss manuals. I am going to head to sleep but if anyone wants to continue where I left off the materials are there.

Kas, great suggestions. Let's do as many of them as we can tomorrow. There are some talk pages we can use to keep these ideas inline with the documentation. This has been an issue in the past.

--art _______________________________________________ chuck-users mailing list chuck-users@lists.cs.princeton.edu https://lists.cs.princeton.edu/mailman/listinfo/chuck-users

Please note that I adapted some material I had previously found in the ChucK source, which was in turn borrowed from the STK. This may or may not affect licensing of the manual but that was the only way in which to document the member functions of VoicForm. Noted here for completeness and corectness, not because I fear Perry and Gary would sue. Let's just put both the stk and ChucK source in our list of quoted source material. Kas.

Wise words again Kas. 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. I think we may include a section of books to read to bring someone up to speed on the concepts. 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. 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. 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. --art 2009/12/16 Kassen :

I added a section titled "extending ChucK" at the end of the manual and moved the chapter on LicK there. This is meant to avoid obscuring the line between what is and isn't a part of ChucK for new users, who will quite likely already be feeling a bit overwhelmed. Similar initiatives like SMIRK and SMULE could find a introduction there too, as could Steve's notes on building UGens using Faust and potential future notes on dealing with the source itself, in case somebody would feel up for that.

I'm close to calling it a night. Some notes; this is a great initiative, it clearly works and it's a lot of fun. This is much, much preferable to Adam going at it alone, chiefly because Adam's time, like everyone's, is limited. It still needs a lot of work though. There are still big gaps and I noted some spots where the explanation may be 100% correct but would also be utterly incomprehensible to anyone without a background in math. I'd like to suggest that this text should be readable to a teenager with a passion for sound/music and a interest in computers who may not have a formal background in either. I think this might lead to starting a description with a informal introduction and perhaps a analogy that may be followed by "programmers would call this [formal description goes here]". I'm not talking about "dumbing things down" here, more about a clear explanation of why we are introducing a subject to make it evident why it will be worthwhile to read about it. Once it's clear what things are good for and how they are unlike other things it will hopefully also be clear that it'll be useful to learn a specialised vocabulary to talk about them.

Yours, Kas.

_______________________________________________ chuck-users mailing list chuck-users@lists.cs.princeton.edu https://lists.cs.princeton.edu/mailman/listinfo/chuck-users

I'm sorting the UGens by type and functionality, dropping the emphasis on ancestry (particularly the STK). This should lead to relevant UGens being far easier to find. I am, of course, preserving the notes on where they came from in the descriptions themselves and the STKInstruments are -of course- in their own section as they are rather unique in function. I already added LiSa (from the online docs) and will also add the various Gen's. I think I'll also add CNoise, based on the reasoning that we should be able to push the single line fix to it to cvs -and a future release- with more ease than we'll be able to get this whole thing completely done and looking acceptable in pdf format. Even without the fix CNoise generates acceptable pink noise, albeit at a rather low amplitude. All of this could be undone if there are cries of moral outrage. As a side-note; I moved "Modulate" to the "oscillators" section as it's basically a advanced lfo. The plain oscillators, however, have a .period( dur ) member function that is especially useful for lfo usage. could we consider adding this to Modulate as well? Yours, Kas.

making this a complete reference, often the example can explain much more than the text. I keep think of some sort of integrated help system with the mini which would have examples as well.

Yes. I want to do that as well, but first I want to finish going over the VERSIONS file and add reference sections for things that were previously missing altogether. For example; for better or worse we have a "StringTokenizer" data type that previously was only documented using terms

Scott; Think some inline examples within the documentation would be useful in like "uh" and "very hacked" :-). This process is becoming not unlike a archaeological expedition. Another issue I have is that I "corrected" a whole slew of references to "sample-synchronous" execution of shreds. Shreds aren't sample-synchronous according to the specs (they are orders of magnitude more precise in timing) but right now we do have a bug in shreds executing in incorrect order due to rounding of durations to integer samps so it could be argued that that text did accurately reflect the state the VM is now -erroneously- in. Sigh.

Personally I still find the ability to 'see inside the VW' really useful with the Audicle it would be great if there was a way of getting a copy of running shreds out of the mini as well.

I wonder what it would take to bolt a modern VM to the existing Audicle code; a straight swap of the directories won't do the trick and I can't deal with the errors that gives.

Yours, Kas.

Rob; 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.

I respectfully disagree. I think there is a significant audience for ChucK that knows about music, knows (something) about sound yet has never used text as a interface to controlling these and wants to try it's hand at that. Not everybody has the luxury of attending classes at Princeton or Stanford and yet these people still need a place to get started. There is no conflict here though, as the current initiative covers both introductory tutorials and a attempt at creating a exhaustive reference to all object types, methods, operations and keywords.

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.

Great! I'm in the process of writing these references and will include "pure". I'm also looking over the tutorials that are up already as I found some bits in there that I have serious doubts about. You can start adding tutorials on any topic you find lacking whenever you have the time and inclination. "pure", to explain from memory, is a keyword to mark member functions for a mother class that is just meant to be extended and not meant to be instantiated on it's own (hence this function wouldn't be called). Ge once explained that he mainly wanted to be able to write "pure fun", as in (my example) "pure fun void cheerfulAbyss()". I can't -off hand- think of a occasion where it will actually affect anything. Still, it will be documented. As will the "--poop" commandline flag, which is about as useful and as frequently used, but it exists and so it needs to be in there. I can think of even more obscure features, but I'll have to re-find the exact syntax. These things aren't either/or matters, in fact we found that some files needed to be split up because only a single user can work on a file at a time so working on more things at the same time will help make the most of the hands and eyes that we have. Yours, Kas.

Agree regarding the sectioning, I had always wondered what the ordering scheme was! Grouping similar elements regarding function/role would make more sense to me and I think would provide a more organic learning experience. Scott 2009/12/17 Kassen :

I threw some of the sorting of the (otherwise great) chapter on operators about a bit.

The version I edited followed the convention of the old manual of putting "new" and "!" (not) in the same section as operators that take only a single input and put "-" (minus) in with those. I moved "!" to the logical operators section, explaining that it's a exception there (in taking a single argument), put minus in with the math as a side-note (where I feel it belongs) and elaborated on "new" in relation to "@".

My reasoning here is that in a older version of the pdf "new" was only mentioned as being similar to "!" in taking a single argument and this was -at the time- extremely confusing to me as -aside from this- "new" is nothing like "not" at all. "not" has been a elementary logical operation since at least Frege, it's the only (non-trivial) single argument operation in binary logic; it belongs in there.

I'm -again- open for debate here, but a sectioning based on role and function makes a lot more sense to me than the old sectioning based on the number of arguments.

Just pointing this out because I don't want to arbitrarily throw stuff about without justification.

While I was at it I added "~" (bitwise invert) that wasn't previously documented aside from Stefan's helpful note on the WiKi.

Kas.

_______________________________________________ chuck-users mailing list chuck-users@lists.cs.princeton.edu https://lists.cs.princeton.edu/mailman/listinfo/chuck-users

This looks great! I'm going to join you all later this week. Excitedly, Mike 2009/12/18 Kassen

Some more notes;

We may need some more stylistic guidelines. There are a lot of sentence fragments (as opposed to full sentences) in the manual and considering the subject matter and the need to frequently break up sentences to illustrate matters in code that seems unavoidable, but I started capitalising those. I think this improves readability.

I also need to apologise to Tomasz as I mistakenly attributed the sentence "In its own screwed-up way, this is kind of nice because....." to him, took it out, then send him a off-list note commenting on the usage of crude language in official documents in a way that I -at the time- thought was amusingly self-referential.

It turns out that line is from the original pdf. For all I know it was Ge himself pointing out the "screwedupness" of the ChucK operator. That was completely my mistake.

On the bright side; I cleaned up that paragraph and will document --shell tonight in penance over my screw-up.

Kas.

_______________________________________________ chuck-users mailing list chuck-users@lists.cs.princeton.edu https://lists.cs.princeton.edu/mailman/listinfo/chuck-users

-- http://michaelclemow.com http://semiotech.org

Sure. Tell me where you want it, what to say and where exactly to link to and it'll be up within a hour or so. Kas. 2010/1/6 Tomasz Kaye's brain

Could someone with publishing access link to the editable FLOSS manual from the chuck wiki?

2009/12/19 mike clemow

This looks great! I'm going to join you all later this week.

...

Excitedly, Mike

2009/12/18 Kassen

...

Some more notes;

We may need some more stylistic guidelines. There are a lot of sentence fragments (as opposed to full sentences) in the manual and considering the subject matter and the need to frequently break up sentences to illustrate matters in code that seems unavoidable, but I started capitalising those. I think this improves readability.

I also need to apologise to Tomasz as I mistakenly attributed the sentence "In its own screwed-up way, this is kind of nice because....." to him, took it out, then send him a off-list note commenting on the usage of crude language in official documents in a way that I -at the time- thought was amusingly self-referential.

It turns out that line is from the original pdf. For all I know it was Ge himself pointing out the "screwedupness" of the ChucK operator. That was completely my mistake.

On the bright side; I cleaned up that paragraph and will document --shell tonight in penance over my screw-up.

Kas.

_______________________________________________ chuck-users mailing list chuck-users@lists.cs.princeton.edu https://lists.cs.princeton.edu/mailman/listinfo/chuck-users

-- http://michaelclemow.com http://semiotech.org

_______________________________________________ chuck-users mailing list chuck-users@lists.cs.princeton.edu https://lists.cs.princeton.edu/mailman/listinfo/chuck-users

_______________________________________________ chuck-users mailing list chuck-users@lists.cs.princeton.edu https://lists.cs.princeton.edu/mailman/listinfo/chuck-users

It's up with a bit of delay. I put it on the front page; IMHO it's both important enough for that and already of a high enough quality to be very useful. I left the old link so that makes it slightly cludgy, but I don't want to make destructive edits to the front page without somebody like Adam or Ge chiming in. Aside from that I personally I agree with your reasoning that the new system is preferable. The one issue I have with the new system as compared to the WiKi (for people with accounts) is that I don't think it's currently clear how new users who find the manual unclear but don't yet have the knowledge to suggest a addition or rewording should suggest areas for improvement. How good are our ties with the FLOSSmanuals site? maybe it could put a "issue tracking" feature on it's wishlist? Kas. 2010/1/6 Tomasz Kaye's brain

hi @Kassen

I thought about having the link appear on the wiki homepage http://wiki.cs.princeton.edu/index.php/ChucK

I imagined it either replacing or being adjacent to the "ChucK/Manualhttp://wiki.cs.princeton.edu/index.php/ChucK/Manual(manual errata, updates, etc)" item. If the current version of the FLOSS manual has addressed all the things mentioned on that page, I guess it can be retired?

I would have the link point to the 'write' page of the FLOSS system, to encourage participation: http://en.flossmanuals.net/bin/view/ChucK/WebHome

I'd have the text link read: "ChucK Manual (User editable)"

Thanks!

2010/1/6 Kassen

Sure. Tell me where you want it, what to say and where exactly to link to

...

and it'll be up within a hour or so.

Kas.

2010/1/6 Tomasz Kaye's brain

Could someone with publishing access link to the editable FLOSS manual

...

from the chuck wiki?

2009/12/19 mike clemow

This looks great! I'm going to join you all later this week.

...

Excitedly, Mike

2009/12/18 Kassen

...

Some more notes;

We may need some more stylistic guidelines. There are a lot of sentence fragments (as opposed to full sentences) in the manual and considering the subject matter and the need to frequently break up sentences to illustrate matters in code that seems unavoidable, but I started capitalising those. I think this improves readability.

I also need to apologise to Tomasz as I mistakenly attributed the sentence "In its own screwed-up way, this is kind of nice because....." to him, took it out, then send him a off-list note commenting on the usage of crude language in official documents in a way that I -at the time- thought was amusingly self-referential.

It turns out that line is from the original pdf. For all I know it was Ge himself pointing out the "screwedupness" of the ChucK operator. That was completely my mistake.

On the bright side; I cleaned up that paragraph and will document --shell tonight in penance over my screw-up.

Kas.

_______________________________________________ chuck-users mailing list chuck-users@lists.cs.princeton.edu https://lists.cs.princeton.edu/mailman/listinfo/chuck-users

-- http://michaelclemow.com http://semiotech.org

_______________________________________________ chuck-users mailing list chuck-users@lists.cs.princeton.edu https://lists.cs.princeton.edu/mailman/listinfo/chuck-users

_______________________________________________ chuck-users mailing list chuck-users@lists.cs.princeton.edu https://lists.cs.princeton.edu/mailman/listinfo/chuck-users

_______________________________________________ chuck-users mailing list chuck-users@lists.cs.princeton.edu https://lists.cs.princeton.edu/mailman/listinfo/chuck-users

_______________________________________________ chuck-users mailing list chuck-users@lists.cs.princeton.edu https://lists.cs.princeton.edu/mailman/listinfo/chuck-users

2010/1/7 Tomasz Kaye's brain

Both Adam and I have spoken directly to the other Adam (confusingly) who runs FLOSS manuals, he seems very approachable.

That's good.

I don't know how the 'subscribe to changes' feature of FLOSS manuals works yet, I don't know if it would pick up new things posted to a manual's discussion pages. I'll check that out and post back. If it does, that might work quite well (though we might need to think about how to communicate that the 'discussion' pages of the manual are the appropriate place for posting these kinds of thing).

I don't think it sends emails for those, actually. What I'm envisaging is a sort of big red button marked "I have a issue with this manual" that would result in a sort of small questionnaire that could be filled in anonymously. Basically I want the tress-hold for filing issues to be as low as it could possibly go. We have to remember that our target audience here is quite likely not -yet- deeply into our little scene. They may not have a list subscription, for all we know they didn't even yet manage to install ChucK. I could even imagine going as far as having a hotlink in the final pdf that would link to this feature. Right now we have no way of getting info from people who try ChucK for a afternoon, then quit, while that would be spectacularly valuable information. In completely unrelated news; yesterday I realised that the "--version" flag wasn't yet in the manual. I think this brings the total up to 32. We may have to admit that a real "complete" manual might take a while. We do need some more new chapters that could be written now if somebody has the time and inspiration but I suspect a huge part of the work over the next few months will be collecting all of the scattered bits and pieces. Yours, Kas.

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.

Yes, i can make Dec 16th. Thanks for the kid words, but I have to say I'm far from a git expert. I wrote the tutorial because I notice that I often feel in a good position to write instructions for beginners when i'm only one step removed from a beginner myself! (that's also why I'd like to contribute to the ChucK docs too). For completeness the git tutorial mentioned can be found at: http://www.basementhum.com/2009/02/version-control-and-maxmsp-part-1.html If we do end up going a SCM route, it might also be worth considering Bazaar (SCM app, like git) and Launchpad (webservice like github). I understand that bazaar was designed with an emphasis on ease of use. It's less feature rich than git, but should be easier to use. It also has a cross platform graphical front end too, which might make the transition easier for people.

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.

Very little markup: That sounds appealing.

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.

Great idea. The examples directory is already really halpful, but a place for written tutorials where we get a sense of why certain design decisions are being made would be really valuable.

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?

The FLOSS manuals site exports to PDF, ODT and HTML, so that may be sufficient for grabbing a current version to include with new ChucK distributions. I didn't get word from Ge yet about whether he'd be okay with this.

We have a wiki. I would be more interested in reinvigorating that space for this project. Maybe we could decide at the end of the sprint that we have outgrown it but I would like to make sure that is the answer before committing to hard to another site.

That could also work. There are a couple of reasons I favour the FLOSS manuals site over a regular wiki: FLOSS manuals has a concept of maintainer, who approves new versions of chapters to 'go public', this hopefully ensures that the canonical version of every chapter is in good shape at all times. Also the FLOSS manuals are designed to be easy to print. I don't know if that's so straight forward with wiki hosted manuals. I noticed that with the ChucK wiki you can't just sign up and use it at the moment, you have to get an invite from a member. Which could also raise the 'drempel' (threshold) for people wanting to contribute. Positive things about FLOSS manuals: It has built in chat facility so that contributors can communicate with one another. Chapters being edited are 'locked', avoids 'merge' complexity. FLOSS manuals is being sponsored by Archive.org in their development of Booki (which will be the next, better version of the site) On the negative side about FOSS manuals: The current site isn't always easy to navigate. The current image manager is a pain to use.

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, I agree that it's better to spend a bit of time early figuring out what makes the most sense, that having to backtrack later.