Hi Sebastien,
Goodness me. There's plenty of strength of feeling expressed in this email. I'm grateful to you for talking this way. I think my motivation for working on spreadcocoon and planetcocoon comes from a similar place so perhaps I can empathise.
I've been thinking about ways we can keep documentation current:
* It strikes me that folksonomy offers developer communities some help here. If documentation can be continuously re-tagged then it's usefulness will evolve.
* Mailing lists similarly could benefit from tagging, with tags like "How do I?", "Worked for me", "Useful" etc.
* Let's make our examples, tutorials and recipes into psuedo-unit tests. This way we can automatically tell whether an example is still relevant or not, as Cocoon evolves. Code samples could be generated automatically from the code itself to avoid cut and paste errors.
What do you think Sebastien? Others?
Take care, Mark
Unfortunately no, we didn't get any feedback on our project, which disapointed me a little bit because I thought there would be more interest in such an initiative. And as I explained in a recent message (http://marc.theaimsgroup.com/?l=xml-cocoon-dev&m=111553930729627&w=2) I've given up because I have neither time nor knowledge enough to do that alone or even with a small group of people (we were only three). I've not given up the idea to participate in Cocoon documentation efforts : I'm in the process of writing a few tutorials on Cocoon Wiki which I plan to translate and make more dynamic on another platform later. But I think that Cocoon is still too unstable to write a whole linear tutorial right now. The only feedback I had and that clearly confirmed my first impression, explained why this initiative was likely to fail (I won't give the name of the author of this quotation because he could find his tires burst tomorrow ;-P but I totally share this impression)
"I think the problem with a project like Cocoon is that, contrary to what you might expect, nobody has a real interest in explaining and documenting things. Most of the people are working with or on Cocoon to resolve their own issues. Many have founded their own companies, are marketing their knowledge and experience. Cocoon is a means to an end, not a product anybody has to sell."
The thing is that I'm sure that everybody doesn't think that way (and that's why I post this message on dev list rather than directly to you Mark, because I'd like to see a constructive discussion developed on that topic) and that many people find that unfair that such a wonderful tool is so unknown. Your initiative with spreadcocoon and others like planetcocoon, cocoondev, and cocooncenter, as well as users questions like this one http://marc.theaimsgroup.com/?l=xml-cocoon-users&m=111581962223771&w=2 show that there is a real need to make Cocoon more "famous" and "prosper" than it is today.
Maybe we could (as someone suggested me in feddback after Cocoon in action give-up) try to unify our efforts and try to start a common Cocoon documentation community, why not on SpreadCocoon. I totally agree about the importance of a good documentation to grow a community and I think it could be a great time for Cocoon to leave its... cocoon (yes I know this was easy :-)) and reach the developer's community, not only Cocoon (or IBM) developer's community but the whole Java server-side developers community, as projects like Spring, Hibernate, Struts, Webwork and so many others have managed to do it. Entropy is not a problem, the volume of Cocoon documentation and Cocoon wiki show that there is a wide community of experts willing to share their experience. The problem is organization, structure, coherence and pedagogy. There must be a real will in this direction at the basis of Cocoon.
And most of all, maybe it's time to completely integrate documentation effort into Cocoon development, to make it part of the Apache "meritocracy thing" as much as coding, because I personally find it too sad that entire Cocoon modules are still coded without being documented at all (eg apples) or with a documentation which is not up-to-date. But this is another discussion which would involve strategic decisions from Cocoon "guru's", assuming they are willing to make Cocoon community evolve that way.
The way I see it we could all join our efforts on a common platform, make it as user-friendly and easy to use as possible and gather all the up-to-date quality tutorials spread all over our different websites in one common place with common conventions and processes. In particular, I think workflow management is essential for a quality documentation, that is it should be reviewed, commented, corrected, updated as often as necessary and all of those steps should be normalized in the documentation platform. And we should take care of integrating all of this newly created documentation in the new Cocoon 2.2 documentation effort.
So WDYT ? Stefano ? Bertrand ? Sylvain ? Upayavira ? Helma ? Others I forgot ? And what about planetcocoon, cocoondev and cocooncenter webmasters, if you can read this, what's your opinion ? How do you see things ? Do you want Cocoon to be better known and so better documented or not ? And how ?
-- Sebastien ARBOGAST
PS : this was my last desperate call to gather documentation efforts in a coherent and rationalized way. If this message doesn't get any answers or does get only negative answers I don't care anymore, I'll do as everyone else, cook my own stuff in my corner. But I think it would be too bad. Don't get me wrong this message doesn't intend to tell you guys how to do things. I'm just a small individual and humble user of this wonderful tool you created. But this list is also made for feedback and it's one of the powers of community development : communication. So this is just my personal opinion, which obviously a few share. As you say in French, "A bon entendeur, salut !"
