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

[Adam Tindale]

Hi,

Great to see you here. I am the current documentation maintainer and
have been absent for a long time now. I love your ideas but I would
love to make some suggestions before we jump in.

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.

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.

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.

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?

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.

In the meantime, I will work out the details to push changes up to the site.

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

These are my current thoughts. What do you think?

--art

On Fri, Nov 27, 2009 at 1:39 AM, Tomasz Kaye's brain
<tomasz.brain at gmail.com> wrote:
> Hi all. I noticed that there doesn't seem to currently be a user
> editable version of the ChucK manual online
> (http://wiki.cs.princeton.edu/index.php/ChucK/Manual this page is the
> nearest thing i found).
>
> While learning things there have been a few cases where I thought
> small changes to the manual wording would make things clearer (for
> instance my recent question about how Envelope works).
>
> I wondered about moving a copy of the ChucK manual to FLOSS Manuals,
> where it can be edited by users.
> http://en.flossmanuals.net/flossmanuals.
>
> I used this site in a recent Ardour booksprint I took part in. It's
> not perfect (sometimes navigation is a little unintuitive), but works
> well. It uses version history (different versions can be compared
> too). A user is appointed as a maintainers of a particular manual.
> Chapters can be edited by anyone with a FLOSS account, but maintainers
> get to decide when new versions of chapters are 'published' (made
> visible in the canonical version of the FLOSS manual, the one that
> guest visitors to the FLOSS manuals site will see)
> http://en.flossmanuals.net/FLOSSManuals/Maintainers .
>
> A few preliminary questions about the idea:
>
> @Ge: would you be okay with the current manual being copied to another
> site, and edited? (i couldn't find license details on the current
> manual).
>
> What do people think of this idea in general?
> Would people use it?
> Would it greatly confuse matters to have one more url for ChucK
> documentation? (any other issues?)
> _______________________________________________
> chuck-users mailing list
> chuck-users at lists.cs.princeton.edu
> https://lists.cs.princeton.edu/mailman/listinfo/chuck-users
>
>