Antonio Thanks for the honest (and heartfelt!?) response.
Please do not take my remarks as any kind of criticism for the developers; I think they are (and have been) doing a great job. I understand too that they are doing what they love and enjoy, as and when they can. Nonetheless, I think that, at the end, what counts is people out there using and, hopefully, appreciating! your code. The big step is then to tell people what you have done, and why, and - most important - how they can use it! It seems, from what you say, that the time is "now" for getting this done. Again, at the risk of being very boring, I will quote from the Hibernate website where they say ( http://www.hibernate.org/38.html ) "There's no such thing as an undocumented feature. If your users don't know about a feature, its a nonfeature. Get rid of it; it's just complicating the sourcecode." A harsh standard to use, but probably a fair one. If we are heading for the next milestone date, then perhaps that's a good point to take "time out" and see: * what docs are currently outdated (deprecated features); * what docs refer to old practices and ways of doing things (eg. XSP) * which features are not documented at all * which features are documented poorly and/or in a very fragmented fashion. Looking through the archives will allow us to spot thorny issues (esp. reoccurring ones) that can be pulled into FAQs or just made part of the docs. Ideally, in future, as questions get asked, it would be great to say "oh yes, thats explained in this doc, or this FAQ". This would help cut down on repeating the same answers to same question. Also ideally, much of the wisdom that is provided here on the list by "those in the know" needs to be distilled into relevant areas in a structured way. A big task, perhaps, but one that would add significantly to the documentation. As for a role I could play; at the moment I am just getting started with trying to learn the whole flow/forms/template, plus the "add ons" such as Hibernate and Java logic classes, technology, with any docs that are available - I am not sure this qualifies me to write anything yet! Having said that, I (and others I am sure - some of whom have already volunteered to write stuff ) would be happy to start perhaps trying to highlight specific areas of work - in fact, there a number of emails on the list that have done this already. I do think there are some very good writers out there - for example, Tony Collen's "Gentle Tutorial" on flow is really great - if we could get to this standard for some of the other areas at a both introductory and advanced level we would have a system that is comparable with the best anywhere... My 1c Derek >>> [EMAIL PROTECTED] 2004/05/04 09:56:14 AM >>> Derek Hohls dijo: > Leon > > I agree that if what works for you is OK, then you > are doing fine. My concern is that there are better ways > evolving and, if they are "easy and clean", I am prepared > to learn them but, and this is my case in a number of threads > (and you have effectively said the same thing here), if this > approach is a limited to a "few in the know" and there is not > sufficient info for others to "get in the know", how can we > evolve as a community of developers with a *potentially* > really good product? Hi Derek: I really appreciate your effort. I think it is a must. The reality is all this is too new stuff and we need time to write some docs. Also get some experience before write it is a good idea. Often, we use our spare time to make Cocoon and the lack of time is what brakes us to give more info. It is not we cannot want to share knowledges at all. :-D In my own case, I stoped my little contributions on the list, because I have a big pressure on work. This is really a big one. I promise to write some docs when I will have time to do that and no one else did it. We can talk around about this lack of docos forever and no docs will be done. I think someone can start the doc and then others will add new stuff or rewrite the doc if needed. If you have now the time to do that, please start it. :-D WDYT? Best Regards, Antonio Gallardo. --------------------------------------------------------------------- To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED] -- This message has been scanned for viruses and dangerous content by MailScanner, and is believed to be clean. MailScanner thanks transtec Computers for their support. --------------------------------------------------------------------- To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
