As a new adopter of cocoon, I beg to differ from some of what I have read regarding documentation. Referring to cocoon version 2.1, it comes with lots and lots docs and examples. I really do not think we are dealing with a lack of documentation or examples. Rather it's a case of knocking what already exists into shape. Especially the examples.
IMHO the examples need to be "rewritten" so that they function at two levels. Firstly, they should be shiny examples of cocoon functionality when played with via the browser. Secondly, each example should be totally standalone in its own sitemap, suitable for lifting from cocoon distribution and used as a template for new users getting started with cocoon. Individually the examples do fine at the first point, although cumulatively they are a rather disorganised mish-mash. At the second level it is a significant task for a new user to disentangle a demo application, that almost does what they need, from other related demos that share sitemaps, resources and other dependencies. I also suspect that a number of examples reflect practices which are now deprecated. Deprecated examples should be removed, there's nothing worse than getting your head around one method only to be told it's a dead technique and something else should be used instead. The coverage of documentation is patchy, some bits are quite well covered other bits rather poorly. When it is good it is very good. The general overviews, concepts and simple stuff is fine, but the detail of serializers, generators, generators and actions etc is where major problems really start to appear. Far to vague and in some cases unintuitive. I have not seen anyone else pointing it out, but after a day or two I was really struck by the fact that conceptually pipelines are not pipelines in any common understanding of the term; rather matchers are the pipelines! This sort of thing is very counter intuitive. Systems that are intuitive require a lot less documentation. On another level, and this is my experience of other leading edge technologies, I think we/you need to consider what it is your users really need. A well done body of documentation will always lag behind any rapidly moving software development activity. Documentation that is out of date is next to useless. So what do you do? Slow down the developers and force them to support or wait for those doing the documentation? Or accept that documentation will never catch up with the leading edge and find another way. I think there is a second way and that is tons of complete working, and documented examples. Such examples should at the same time be examples of the leading edge and best practice. A good clear and relevant example will always get you 70% of where you need to be. Having got that far you can generally figure out the rest using the wiki and other resources. Regards Fergus. -- =============================================================== Fergus McMenemie Email:[EMAIL PROTECTED] Techmore Ltd Phone:(UK) 07721 376021 Unix/Mac/Intranets Analyst Programmer =============================================================== --------------------------------------------------------------------- To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
