Yes, he does, though I disagree on some of the finer points e.g Cocoon is not a "leading edge" application any more and, no, its not always "intuitive" (such a fuzzy and subjective term); simply because a number of its concepts differ sharply from many other web development frameworks. I would also not suggest to rewrite the existing examples - waaaay too much work! - but simply to add "template" applications which each standalone and can be repurposed or extended to users' specific needs. Some input from the community would help rapidly identify good case studies. To my mind - and this reflects my experience in the workplace - as well as other 'voluntary' organisations - nothing actually happens without a
champion to drive it. That person has a passion for the task at hand, and sees it through to completion. In this case, such a champion would have to have a good working knowledge of Cocoon (although not necessarily as a developer), with strong English writing and conceptual skills. This person would need to look at synthesising all the docs on the wiki and on the main/official site. Older stuff needs to be carefully hidden away and deprecated stuff marked clearly as such. Links to key outside resources (e.g. tutorials or introductory articles) could also be gathered in one place and annotated as needed. A "one stop Cocoon shop". I would actually suggest that the project adopts one single platform for its documentation and this would likely have to be a wiki. The advantages of this are: * reduce scatter and "where do I find this?" syndrome * ability to do very rapid updates * allow only developer access to key pages, while still letting users add their own - *anyone* can add comments on "discussion" tabs and this will help the official pages to be brought up to speed. (It would be cool if "official" pages could be colour coded in some way to highlight them...) [Side note: I have a feeling that wiki design has evolved since the Cocoon wiki was chosen. While its adequate for the basics, many other software projects have chosen the wikipedia-style wiki as it allows for a lot of extra flexibility and options eg. navigation; ability to have discussions on each page; categories etc.] >>> Jonathan Hipkiss <[EMAIL PROTECTED]> 2007/05/30 11:48:29 PM >>> I think Fergus has it spot on here. Most developers operate by first copying another example of something that works, then they modify it to their own use. As a fall back, complete technical documentation of the technology is then needed to detail how it operates and what its syntax, grammar etc. are. Lastly, for the more complex techniques it can be useful if a very simple example is shown in a step by step approach to grasp the concepts before delving into the deeper "all sing all dancing" examples. Jonathan Fergus McMenemie wrote: > 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. > --------------------------------------------------------------------- To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED] -- This message is subject to the CSIR's copyright, terms and conditions and e-mail legal notice. Views expressed herein do not necessarily represent the views of the CSIR. CSIR E-mail Legal Notice http://mail.csir.co.za/CSIR_eMail_Legal_Notice.html CSIR Copyright, Terms and Conditions http://mail.csir.co.za/CSIR_Copyright.html For electronic copies of the CSIR Copyright, Terms and Conditions and the CSIR Legal Notice send a blank message with REQUEST LEGAL in the subject line to [EMAIL PROTECTED] This message has been scanned for viruses and dangerous content by MailScanner, and is believed to be clean. --------------------------------------------------------------------- To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
