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
