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

[Adam Tindale]

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