[chuck-users] The ChucK Method Book

[Zed A. Shaw]

On Fri, Jan 28, 2011 at 02:06:59PM -0500, mike clemow wrote:
> If I might opine upon this subject.  I think that a community-written
> manual/usage document is a great idea.  I think for something open
> source like Chuck, we ought to spearhead an effort to both document as
> well as proselytize using Floss Manuals - http://en.flossmanuals.net/
> 
> I know we've had this discussion before, but if this is to be a method
> book, or something like that, I don't see why it should be there
> instead of some pdf.  Sharing a document is so hard that way.

So, writing one of these isn't hard.  For me it was a piece of cake to
write http://learnpythonthehardway.org/ and really the only thing
holding me back on The Chuck Method Book is time.  If people wanted to
do a community version of it I have a some suggestions that will help
make it actually work.

You'd think writing a book with a bunch of people is as fun as writing
software but it's actually a lot more difficult.  The problem is that
everyone has their own voice and while source code forces everyone to
basically talk the same way, with English even slight variations can be
irritating to a reader.  The other problem with completely community
based books is they become disorganized and are never finished, so you
have these half-done and highly flawed works out there confusing people.

On the flip side, there the problem of an author not having enough time
or not being enough of an expert to generate source material and copy.
A community can produce a lot more material than one person.

What I suggest you do is you combine the two.  You have a wiki of "ChucK
Recipes" or similar that people can just go crazy with and write up how
to do anything.  They need to rate them by difficulty and whether it's
say a tip/trick or an exercise type of tip.  The model to follow is
http://vim.wikia.com/wiki/Vim_Tips_Wiki to see how this is done right.

Now, this ChucK Tips wiki is allowed to be disorganized and have a loose
structure, so that let's everyone contribute material.  Choose a
consistent Wiki format that supports code.  The tips wiki purpose is to
*not educate or guide* but instead to be a *reference* for getting
things done.

You then have the "official" ChucK Method Book.  This book should be
collected and edited/written by one or two people.  I prefer one person
who can write since then the book has one voice and can be finely
crafted.  The job of the CMB editor is to take tips and exercises from
the Tips wiki, combine them with a guided set of exercises with the goal
of taking someone from nothing to capable in play ChucK music in 1 year.

Of course, some people will go through the book faster than a year.  But
if you plan on 52 exercises, 1 per week, then people can structure that
any way they need.  It then gives you a solid guide for how the book is
built, and sets up all your topics and an end point.

After you've got this editor in place, and the tips wiki filling up,
writing the book is literally a couple hours an evening of cleaning up
tips and putting them in the right lessons.  I did this and wrote LPTHW
in about 3 months, with maybe 2 months of real work on it.

One word of warning though:  People will scream up and down that they'll
contribute to the book and that they know exactly how to teach people.
99% of these people are completely full of it.  They'll write little
tips, they'll write code, but most of them don't know the first thing
about teaching a concept or really even writing about it.  Don't get
your hopes up that you'll have hordes of really great lessons just
handed to you.  You will have to finely craft the manual if you want it
to be good.

The editor will have to focus on really getting the voice, structure,
and flow right and shouldn't assume anyone else is going to help unless
they prove themselves over and over.

If you want help getting a sphinx setup going (that's what I used on
LPTHW) I can give some pointers.

-- 
Zed A. Shaw
http://zedshaw.com/