Hi, I may have something to suggest concernig the new documentation effort. The main problem that I had to face while begining to work with Cocoon was the enormous gap between the level of the first tutorials I found on the wiki or other sources like theserverside.com or IBM DeveloperWorks. I mean those detailed articles about particular features of Cocoon are very useful as a reference when you know how to use Cocoon but it's very difficult to integrate things when you are a beginner. And it's even worse with samples because either they make a lot of basic assumptions to fit precisely what's said in the parallel documentation or wiki article, or we get enormous technology demonstrations like CHS, which are very difficult to dive into.
And as it seems, the new documentation effort is mainly aimed at reviewing and reorganizing existing articles and then filling the gaps with missing articles. The result of that process will be at best a wonderful reference, but it won't solve this gap between "getting started" stuff and everyday-work with cocoon. So my suggestion is the following : all the technologies I've learnt, Java in first, I've learnt them thanks to some great books based on case studies explained in parallel with theoretical issues, in order to apply things concretely and progressively as you discover and understand them, while building a common application by aggregation. Sort of a big tutorial like you can read them in Hibernate in Action or J2EE tutorial for example. The objectives/topics that should be covered in such a "Apache Cocoon in Action" tutorial could be : 1st part : Getting started with Cocoon - What is Cocoon ? History and theory - Installing Cocoon on Tomcat : building process, blocks description etc. - Hello Cocoon : classical but always efficient to demonstrate and reassure people... - Integrating Cocoon into your development environment : application/web server, source versioning control, build tools (ant or preferably maven), IDE (eclipse and tools like xml editor, anyware-tech plugins, etc.), information sources (mail lists, websites, etc.) - Case study presentation : goals to achieve, overview, etc. the exact nature of this case study is still to determine but I think it has to be as common as possible. For example it could be a complete website with a backend 2nd part : describing the basic concepts and giving links to the new reference for details each specific feature. Each chapter would end with integration of concepts into the case study - sitemap concepts + matchers, readers, protocols, modules - generators + quick introduction to XML - transformers + quick introduction to XSLT - serializers + quick introduction to XHTML/CSS - resources and views - flow control inside the sitemap : selectors, redirecting, error handling, actions,etc. 3rd part : advanced concepts making it possible to optimize things, to improve performance and accessibility of the case study application - caching - internationalization - forms (with an overview of the different forms technologies, not only CForms, in order to understand why CForms are a good choice) - control flow (with a introduction to apples if possible) - XSP and logicsheets 4th part : integrating Cocoon with other tools to add a backend to the sample application - authentication framework to protect the backend - introduction to Java, design patterns and avalon - introduction to Hibernate and AndroMDA for data representation using an embedded HSQLDB database + integrating Hibernate into Cocoon - advanced CForms and control flow to edit Java Beans - integrating other blocks with small introduction samples for axis, batik and other interesting blocks ..... This is just a suggestion and I obviously miss many things because I've been working with Cocoon for only a few months, but I think that this content should help people to fill in the gap and getting to know that wonderful tool better. Moreover this documentation could be written and reviewed in parallel and tight collaboration with the new Cocoon 2.2 documentation effort to make sure that the information is accurate and exact and to keep stuff in sync. And it could be written and reviewed/corrected progressively with the help of users giving feedback about what's missing and what should be removed. What do you think ? Would anyone be interested in helping me to write such a documentation ? Do you have ideas about technical infrastructure we could use : wiki, mail lists, maybe forums and IRC channel which are ideal for user feedback and easy communication, documentation format (forrest, SVN repository, writing and reviewing process) ? What about work team organization (I find this very important to avoid stepping over each other's feet and make sure everything is correct and precise, even if it's longer) ? What about translations : would some people interested in translating that documentation to other languages as we write it (french ? spanish ?) maybe a few polls on local development communities would be necessary to determine what languages are worth translating to. What about a common website area to centralize efforts and make the project known to users and potential writers ? Maybe it's not necessary to talk about the content in the first place, to insist on whether or not it would be interesting and if some people are willing to participate, and what could be the general shape of such a project... I'm waiting for your opinions. FTR, I should precise that right now I'm working on a big project using Cocoon as its core XML server and it's my first project using Cocoon, which implies that -> I won't be able to spend my whole days on this -> I don't have much knowledge about Cocoon which means that even if I intend to use my newbie aspect to make the documentation accessible and my great interest in Cocoon to make this documentation successful, we would need many interested diverse-skilled people to bring this to realty in a reasonable time (that is before Cocoon 4 at least ;o) Regards -- Sebastien ARBOGAST
