The Kolesnikov Tapestry book has one of the worst indexes I've ever come across and stands as a good example of how not to do it.
Having a good index is a very important part of any successful technical book. Indexing a book well is a non-trivial matter and shouldn't just be a last minute thought.
I'd also suggest a good set of Appendices - one, at least, should list the components and what parameters they take.
Anyway, something to think about. p. Quoting Alex Kotchnev <[EMAIL PROTECTED]>:
I've created a new project for the proposed book at http://code.google.com/p/tapestry5-book , and posted the proposed table of contents at http://code.google.com/p/tapestry5-book/wiki/ProposedTableOfContents . Now that I'm looking at it, it's a little disappointing as the TOC doesn't really have anything new in it (e.g. some of it is covered in tutorials, other is in the project docs, etc). However, I guess that the content really can't be all that different - it's all about building web apps, covering the same materials as the other documentation. In the end, I think that the book will be different from the other existing documents based on its style and breadth of content, and not so much in the topics it covers. Anyway, I would like to create a mailing list and add everyone who has expressed an interest in contributing to the book. Unfortunately, Google Code doesn't have mailng lists, so I'll probably have to look around for that (Nabble, maybe?). Any suggestions would be welcome here. In terms of moving the proposed TOC forward, here are some of my next steps : 1. Attribute the main sections of the project documentation into possible chapters in the book. 2. Discuss feedback from this list on the content of the proposed TOC : e.g. any alternative ideas on how to organize the book, changes to the proposed chapter titles, order, etc. It would be great if there are any volunteers to investigate some of the issues that were discussed previously in the thread below, I'll probably post the needed tasks somewhere on the wiki as well. When we get our mailing list set up, I think that individuals or groups of individuals can claim ownership of each chapter (and thus get "voting rights" on the TOC, chapter layout, further modifications, etc. Cheers, Alex Kotchnev On Thu, Aug 28, 2008 at 4:59 AM, Hugo Palma <[EMAIL PROTECTED]> wrote:inline Alex Kotchnev wrote:Would there be any value to having a top-level domain for the book (e.g. tapestry-book.org or something like that), or can we find it a home for the book somewhere under the Tapestry namespace ?A top-level domain should brink more visibility to the effort. Also, in the future we could probably spend some of the monetary payback to pay for the domain and some hosting solution so that we could include the live version of the book application and other cool stuff. Still, for now i think we can live with a project on some project hosting site where we can host the book files and wiki.A note on the potential mode for governing decisions : I was thinking that in the next couple of days, I'll post a list of possible chapters to include in the book. Then, we can collect a first set of volunteers for people take ownership of each chapter. After the initial set of volunteers, the chapter owners will vote on addition of new chapters and giving ownership of chapters to new contributors (if needed).Shouldn't the outline be already created in a tapestry-book wiki ? We could decide on where to host it and then move the discussion to the dedicated list and use its wiki for the outline. On whether the book would cover additional libraries (e.g. chennilekit,t5components): I think that after we get to a good place where we have enough content on the core we can probably spend some time on those as well, possibly with contributions from the project owners. Conceptually, it would be impossible to include all 3rd party / contrib libraries in the book (or it will always be incomplete) . I guess my point is that I think we'd want to describe Tapestry and most essential additions (e.g. t5-hibernate, t5-spring, etc).While it's true that if we go down the line of including third party libraries it will always be incomplete and maybe unfair to some i think it would be important to cover the ones that we consider the most used. We could go with a voting process where each one would say the top 2 or 3 third party libraries in his opinion. The top 2 or 3 would get included in the book. Cheers,Alex Kotchnev On Tue, Aug 26, 2008 at 11:13 PM, Thiago H. de Paula Figueiredo < [EMAIL PROTECTED]> wrote:Em Tue, 26 Aug 2008 23:30:41 -0300, Alex Kotchnev <[EMAIL PROTECTED]> escreveu: Here are a couple of the next steps that I think would be useful in movingthe effort forward:Nice! I was thinking of posting a similar set of questions here . . . :) 1. Post a rough outline of the table of contents in the book (initially,probably on the wiki).+1 I can't thing of another way of kicking off this project. I just suggest another step: just start writing real content after refining the table of contents, thus avoiding some Frankensteinian results. 2. Experiment somewhat w/ the publishing / collaboration methodology. +1 3. One of my areas of concern is how the merging of xml/docbook would workin the long term. I know it's just text, but I'd imagine the doc-book project will probably have it's own way of editing content and converting it into docbookI always tend to prefer handwriting documents and code over tools (so Howard's Tapestry 5, I guess :) and we could define some policies related to use of tags, whitespace and maximum line length. I think the merging problems would be reduced this way. 5. I think it would be best if we use either an existing "examples"project (e.g. like jumpstart) or take one and modify it to fit under a particular theme that gets developed throughout the book+1 to find one single application that will be developed throughout the book. It should be hosted in some repository (SourceForge, java.net, etc). Maybe it could even be integrated as a Tapestry subproject. Here are a couple more outstanding and pesky issues that are still verymurky in my head : 1. Would a book like this be published under some open source license (e.g.I know that there are a couple of 'open source' books, e.g. the CVS book the SVN book, etc) , maybe Creative commons ?It would be really hard to define each contributor share in the profits, so I think some open license and proper credits would be a better fit. This would also attract more people to Tapestry 5, as there would be more free documentation in the internet about it. The open source book does not prevent a printed version of the book. 37signals, for example, sells the PDF and printed versions of ther Getting Real book, but it can be read for free in their website ( http://gettingreal.37signals.com/). By the way, very interesting read. :) 2. How to make the decisions regarding a book's content ? Would it be somevoting involved ? E.g. if someone thinks a particular chapter should be in the book, and others don't agree, how to decide if the chapter is in the book or no (here comes the concept of "committers" again)Looking at several different projects , there are two main ways to organize a team: 1) Benevolent dictatorship. The team has a leader that listens to everybody, but he/she decides. 2) Straight democracy. We could (re)use the Apache model (my choice). 3. Can we continue using this T5 users list or discussions regarding thebook are a distraction ?IMHO, the Tapestry users list is already used for two very different Tapestry versions, so we should open some other communication channel (forum, another mailing list, maybe a tapestry-book one). Another questions: 4) Would it only cover 1st party packages or 3rd party ones (t5components, chinellikit, etc) too? My first thoughts: yes, and the 3rd party packages would happily write about their creations. I would. :) 5) Would it also have a cookbook section or chapter? My answer: yes, and we could reuse the Tapestry wiki pages here. The book would then be something like a central place to find additional information, something similar to what the Hibernate document is. I'm really very positively surprised by the amount of feedback so far, andI'm very curious to see how far we can take this. Please comment on any of the ideas above, rip me to shreds if you think this is the wrong way of doing it.I second your words, Alex. This is going to be a really interesting project, involving people from many places around the world, having different first languages, different visions, but sharing the same goal: promoting our favorite Java web framework by writing a good book about it. :) Thiago --------------------------------------------------------------------- To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
--------------------------------------------------------------------- To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]