It is certainly an interesting idea. I think HIbernate follows a similar approach; they have a Wiki (Confluence, perhaps) and they "scrape" it to get the packaged documentation.
We could look into running a more involved Wiki, perhaps from tapestry.formos.com. Confluence would be reasonable, as I can get an open-source project license for any of the Atlassian products. The problem with this is oversight; writing a book in any format consists of a lot of dull work. In an open community its hard to motivate people, without a direct stake, to do that kind of dull work. On Mon, Aug 25, 2008 at 9:03 AM, Alex Kotchnev <[EMAIL PROTECTED]> wrote: > 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 > -- Howard M. Lewis Ship Creator Apache Tapestry and Apache HiveMind --------------------------------------------------------------------- To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
