First of all, I apologize for the long post in advance, I couldn't figure out how to make it shorter.
I've been thinking about how much I miss the unborn "T5 in Action" book. I spoke to Howard a while back and he said that it's unlikely that a new revision of the "Tapestry In Action" (from Manning) would happen : understandably, he has the framework to worry about, not the books, and it's unlikely that he'd have 1 year to take away from work and write a book. Thus, I've been trying to figure out ways to substitute for the missing manuscript. Here are my impressions so far: * The T5 book from PacktPub is a nice intro, but it's out of date and it's kinda shallow * The wiki has some nice content on it, but it's disorganized and a little too random: you may find something useful on a subject, and then, you may not * The project docs are often quite useful and often times quite deep, but they don't have enough examples to put things in context * The tutorials are all focused around "getting started", and don't have enough substance * Finally, the example apps (e.g. JumpStart, t5-acegi example, shams, etc) are extremely useful; however, (by design) there's little narrative surrounding them to explain how and why things work the way they do. Thus, the bottom line is that one has to hunt down 5 different resources (possibly more) to pull together a coherent picture , especially when one goes deeper than the "getting started" stage. Now, I clearly don't know enough about T5 yet to write a book myself (as much as that sounds appealing to the ego) and it's unlikely that I could possibly dedicate the time and effort to do it all. So, I had the idea for a while that it would be extremely cool and useful if a bunch of the people interested in T5 could get together (incl. myself) and write a book on the subject. Tim Sweetser jumped in with the idea on the IRC channel that we could do a "collaborative online book" : put together a rough outline of the potential content (chapter and section-wise), then let users contribute to the effort by filling in the blanks (with some editorial oversight). So, if something like this were possible, a bunch of people can get their minds together, each one contribute a chapter or two and kick off the effort. This way, each one person can focus on a subset of the problem, describe it in sufficient depth (e.g. research the areas that he/she is unfamiliar with), and not weigh down anyone in particular with an enormous amount of effort (such as writing a whole book). Surveying the landscape, similar things already exist. Tim Sweetser mentioned that Django did something like this. I know that Grails has quite a thorough user manual that covers most of the important areas of the framework. I also remember bumping into the PHP manual where people could comment and add relevant examples and such. So, in conclusion, this is possible, people have definitely done it, and it's HUGE for the community around the project. So, the next question is, how should something like this be done ? * The Wiki seems like a no brainer to start with, add the TOC and then allow people to contribute. The potential problem with it is that code and the examples can easily become stale. I know that the examples of the Grails user manual are somehow compiled and checked that they run before a new version of the manual is published. * Another option seems to be putting a bunch of Docbook files in SVN and collaborating through SVN to move the book forward. The upside of doing something like this is that it gives us an immediate perk of being able to export a printable version of the book. Downside is that contributing to the book is not all that easy (e.g. some DocBook knowledge needed, SVN access, etc) * Yet another option could possibly be Google Docs. The upside of this is that the learning curve is about 0 and publishing it in some decent format is easy. The downsides are that possibly can be a PITA to share the doc w/ the right people * Tim mentioned that maybe some kind of CMS would be nice, but at the same time, it might be a bit of an overkill. So, in summary, here are a laundry list of requirements: * The book should have thorough coverage of the different aspects of working w/ T5 : from getting started to components and advanced topics (e.g. IoC magic) * The book should be easy to contribute to - comments, code examples * It would be nice if there is a decent printable version * It would be great if we can leverage some of the existing resources: e.g. wiki, example apps, tutorials, etc. * It would be nice if we can come up with a way to keep the code in the book in working order (e.g. if we reference some of the example apps, that could do wonders in keeping a runnable version of the examples) * There should be some structure in the book (e.g. more than just the flat wiki namespace) * There probably should be some editorial oversight to prevent one of the known trolls from putting garbage in. So, here come the questions: 1. Does this sound like a good idea ? Maybe I don't know the right places to look or my mind is too shallow to keep them all together... 2. Is there an existing place where this effort can be channeled better, instead of creating something new ? 3. If this could be a new effort (e.g. a project tapestry-doc, maybe??), what are any additional requirements for doing it (in addition to some of the ones listed above). 4. If this is to be done, what's the best way of doing it ? I'll research to see if I can find out how Django did their, but general feedback & ideas on the technicalities would be very useful. E.g. how do people collaborate best on writing a book ? Is there an existing service that might make this easier ? Any comments and feedback on any of the topics above would be greatly appreciated. Thanks, Alex Kotchnev