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/