Computing Thoughts Community Book Creation: Python 3 Patterns and Idioms by Bruce Eckel September 25, 2008
If Python's what I want to do, I should write that book about it. Herein I muse about how to create a book relying largely on community input and help.
Another epiphany from hanging out with the Pythonistas in Brazil: After a dozen years, Python is still the only language I get really jazzed about. I should do something about it, so that I can do my consulting and speaking and training in Python rather than languages I'm not so thrilled about. To wit: write that book.
Several years ago I started Thinking in Python, which has been in limbo for quite awhile. But when I was actively working on it, I was getting some great input from the community. What I'd like to do now is:
Pull out what's good from that book
Update it all for Python 3
Figure out a way to create the book primarily from community input
Post the current electronic version as a set of web pages
Find interested folks to help in the management process, so that I can focus on the core of the book without getting distracted onto administrative and other issues.
The best way to produce a quality book in a short time is if I can concentrate on editing, writing and rewriting. I know from experience that noise from the other things can easily sidetrack me.
The working title is Python 3 Patterns & Idioms (for various reasons I may not be able to use my "Thinking in" title; don't ask). It would not be a book that develops from simple to complex the way that Thinking in C++ and Thinking in Java do, but rather a collection of different programming techniques, which lends itself better to a collaborative effort since you don't have to worry so much about whether basic things have been covered (it won't be an intro book) or the order of coverage, etc. Each chapter becomes a standalone short article.
Important tenets of the book:
The electronic version remains freely available in perpetuity
Everyone gets credit for contributions
Like my other books, all examples will be automatically extracted and tested to ensure code correctness (and so the code is packaged with the book). I think the tests should be part of each example, and I think Nose is the least intrusive/noisy of the Python testing systems.
The print version will be derived from the electronic version, but won't be the same (the early edits will go back into the electronic version, but at some point when I'm doing layout and polishing the print book will "disconnect" and maintaining both becomes prohibitive).
What's the best way to allow people to work on this? Version control or something like a controlled wiki or Google pages?
What's the best gatekeeping approach? I'm thinking that you just get commit permission from a gatekeeper, and if it's later discovered you are behaving badly you get kicked out.
For the print book I'll need everyone who touches it to sign a release form. That's probably just part of the gatekeeping process.
I'm thinking that Restructured Text is probably the best candidate for input. Is there something newer and better?
It might be interesting to allow readers to use easy_install or something similar to install the code package from the book, so they don't have to mess with dependencies.
What about easy feedback from readers who haven't passed through the gateway? The "Backtalk" system (which I note has been emulated elsewhere) that I created for Thinking in Python was a very early version and became unmanageable, mostly because of spam. Perhaps a similar system that links to an issue tracker like Trac? However, it's possible that the format of this book is such that each paragraph doesn't need to be tagged as in Backtalk. If each pattern or idiom is a small chapter, and each chapter has a single "feedback" button that links to the issue tracker then that will probably be adequate granularity.
Bruce Eckel (www.BruceEckel.com) provides development assistance in Python with user interfaces in Flex. He is the author of Thinking in Java (Prentice-Hall, 1998, 2nd Edition, 2000, 3rd Edition, 2003, 4th Edition, 2005), the Hands-On Java Seminar CD ROM (available on the Web site), Thinking in C++ (PH 1995; 2nd edition 2000, Volume 2 with Chuck Allison, 2003), C++ Inside & Out (Osborne/McGraw-Hill 1993), among others. He's given hundreds of presentations throughout the world, published over 150 articles in numerous magazines, was a founding member of the ANSI/ISO C++ committee and speaks regularly at conferences.