I think a character in Kurt Vonnegut Jr. Cat's Cradle has a fair bit of advice on indexing your own book (she says "never").
-----Original Message----- From: Alex Kotchnev [mailto:[EMAIL PROTECTED] Sent: 05 September 2008 05:35 To: Tapestry users Subject: Re: T5 : [ANN] The book - (Index & Appendices) I know from experience that creating a good index is just a lot of grueling work . I really haven't given much thought to the topic, as it seems that it's quite far away in the future. Also, not to diminish the importance of the index; however, at this point, it is not very clear exactly what the printing options for the book are going to be (e.g. purchase on lulu, print a pdf on your own), and it's not even a "proper" technical book yet (e.g. no publisher or anything like that). So, once again, the index is very much in the future. Cheers, Alex Kotchnev On Thu, Sep 4, 2008 at 9:22 AM, <[EMAIL PROTECTED]> wrote: > I know this is very early in the piece, but what do you intend to do about > indexing the book? > > 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 >>>>> moving >>>>> >>>>> >>>>> the 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 >>>>> work >>>>> >>>>> >>>>> in 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 docbook >>>>>> >>>>>> >>>>>> >>>>>> I 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 >>>>> very >>>>> >>>>> >>>>> murky 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 >>>>> some >>>>> >>>>> >>>>> voting 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 >>>>> the >>>>> >>>>> >>>>> book 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, >>>>> and >>>>> >>>>> >>>>> I'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] > > --------------------------------------------------------------------- To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
