[chuck-users] The ChucK Method Book

[mike clemow]

Hey Zed,

I think your idea is great and I really appreciate your advice about
how to write a decent educational book.  I have never written an
educational book--although I have experience doing tech documentation,
which I know is a different animal but should help with the clarity
thing.  Also, I have enough experience teaching to know that I have a
lot more to learn about educating people.  I think that's what makes
teaching so hard.

Anyway, I would love to contribute little lesson seeds to a growing
garden of possibilities that will later be collected, curated and
organized by an official author (or two) into some coherent text.
Another thing that this collection would be really helpful for is
generation of lesson plans for people who are using Chuck in a
classroom setting (specifically outside of Princeton and Stanford,
since they have well-developed curricula already).

Sphinx...  you mean this?  http://sphinx.pocoo.org/index.html

At first glance it seems to be Python specific.  Can you explain how
will that help us with Chuck examples?

Best,
Mike


On Fri, Jan 28, 2011 at 3:52 PM, Zed A. Shaw <zedshaw at zedshaw.com> wrote:
> 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/
> _______________________________________________
> chuck-users mailing list
> chuck-users at lists.cs.princeton.edu
> https://lists.cs.princeton.edu/mailman/listinfo/chuck-users
>



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