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

[Tomasz Kaye's brain]

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