In my opinion cocoon needs to start architecting itself towards four types of cocoon consumers:
Presentation Developer: This person uses editors to define style sheets for transforming data into presentation layers. This user should not be concerned with the extension mechanism of cocoon. In a real company, this user would be a graphic designer. Should this user need some special kind of transformation, they would ask the next a Content Developer. Administrator: This person is responsible for maintaining the health of the cocoon instance. This user would typically be a network engineer at a company. They should have functionality to track throughput and performance and get an idea of the kind of volume being handled by cocoon via some statistics pages. Content Developer: Data is the prime responsibility for the content developer. He builds data engines using custom generator classes, static XML and various other mechanisms of cocoon. This user is served by a programmer in a company. The developer Is concerned only with the interface to cocoon and not with any of the internals. He doesn't need to know why things work, he just needs to know that if he implements interface x and generates content via sax events, then cocoon magically spits out his XML. Cocoon Developer: This is a consumer that is concerned with altering the cocoon distribution. This person has varying levels of knowledge of the internals of cocoon and seeks to contribute to the general product via commits to CVS. ----------------------------------- To accomplish this we need, IMHO, to implement a few things in cocoon. The suggestions are annotated with the target roles indicated below their title. it is for these target roles that we do the task. Document the API: For (Cocoon Developer, Content Developer) Developers of cocoon should go through the entire API and document it. Using a tool like Jalopy, all of the source code can be formatted to standards set in the jalopy options. For each entry that is not documented, a todo list can be generated and worked through to remove all of the todo tag entries. Cocoon can be used to parse the javadoc files and, using XSLT, extract all of the todo entries. This would give the consumers the ability to use the API more effectively. Abstract Out References to third party libraries: (Cocoon Developer) Anytime the Cocoon Developer needs to build a new custom extension to cocoon, he should have to only import the cocoon.jar file into his classpath to compile. All of these interfaces will then be documented in one API document set for easy consumption. This would be accomplished by identifying all entry points and facading them with interfaces. So the avalon request object would instead be org.apache.cocoon.api.Request. The user deals only with the interfaces and not with anything internal. Convert logging to use Log4j: (Administrator, Content Developer, Cocoon Developer) This would involve converting Logikit logging to Log4j logging mechanisms. Although pervasive throughout the code, the changes are mostly a bunch of search and replace activities. It can hardly be denied that Log4j has won the Java logging market. There are already a number of professional tools used for viewing Log4j output. Such tools as those used in consuming JMS logging events are used by network engineers all over to monitor health of the system. There is little point trying to fight the tide. Making Cocoon use Log4j would have the advantage of allowing these network admins to configure single Log4j property files for their whole platform. Build documentation specifically targeted at each user role: (all) This documentation should include getting started guides for all four types of users and varying levels of tutorials. For instance Presentation Developers might get a tutorial on XSL and XML. Content Developers would get current tutorials such as making your own generator and introduction to forms in XSL. In addition, other tutorials such as the sitemap tutorial would be common to all roles. This documentation should be sectioned appropriate to the roles. Create a distribution stripped of every example except a single XML-XSL transform welcome page for use as a starter point. (Content Developer) Change the Libs format: (Content Developer) The libs should all be packaged into one big jar containing each of the other library jars. This library would contain a classpath for each of the entries in the big jar file. This would hide internals from the cocoon developers. A new jar called cocoon-ext.jar. (Content Developer) This jar would contain only the needed classes for compiling extensions (such as generators) to cocoon. It would be for users to mount in their development IDEs instead of having to mount the entire cocoon-all.jar. In the distribution, a new directory called dev-libs would be created and this jar would be placed in there. All properties and xconf files that the user doesn't need to routinely edit would be packed into the cocoon-all.jar. (Content Developer) The code loading these files would be adapted so that if a user chooses to provide his own xconf files (at his own risk), he can do so. Perhaps the code looks for custom-cocoon.xconf in the classpath and if it doesn't find it, then it loads the default one in the cocoon-all.jar. Finalize a Sitemap Schema: (Content Developer, Presentation Developer) Being able to validate against the schema would be a big help to these two roles. Comprehensive reference manual: (all) This would contain things such as a dictionary of common terms and a list of the generators and what each does. It would be brief reference material used to help the cocoon consumers. All properties for the cocoon.xconf files and various other files would be enumerated and so on. ----- Original Message ----- From: "SAXESS - Hussayn Dabbous" <[EMAIL PROTECTED]> To: <[EMAIL PROTECTED]> Sent: Monday, January 27, 2003 8:52 PM Subject: Re: proposal: "The Newbies Competence Center" > From the ongoing discussion we (the users) stated, that : > > * currently the docs do not really separate between > cocoon-users and cocoon-developers and cocoon doesn't > imply an obvious separation. > > * the documentation seems to be more developer centric, less > user centric. > > * especially the newbies often get into trouble, because > they feel, they have to learn the concepts in depths before > they can get someth8ing out of cocoon. > > therefore we started this "newbies competence center" approach. > i personnaly whish, that eventually the whole cocoon documentation > will be better separated into developers issues and users issues, > where my definition (biased from the discussions) is a bit fuzzy: > > user: *uses* the given infrastructure as is > developer: *creates* his own add ons to given infrastructure > > I get troubles when it comes to xsp programming, which clearly > sits between the chairs. But even there i see a bunch of prepacked > ready to use logicsheets ready made for the "users" and > the self made extra logicsheets from the developers... > maybe this is a little simplistic, but it may hold as a first > approach towards separating user concerns from developer concerns. > > another argument was: the user does not deal with internals nor with > philosophy under the hood (like avalon framework, etc.) The developer > in contrary does. But even here there seem to be at least two kinds > of developers at work: those who do "simple" add ons (whatever > simple means) i name them "application programmers" (they won't > dive deep into avalon) and those who create complex additions to the > cocoon base, who may be labeled as system programmers. > > all of this is not so easy and should be separated out more clearly > in the next steps. I am pretty shure, if we keep with KISS, we should > come out at least with a usable beginners doc though ;-) > > regards, hussayn > > Tony Collen wrote: > > > > Remember, the docs are for the users, and unfortunately, the developers > > might have a different idea about how the information "should" be > > categorized. Or maybe our problem is making the distinction between > > "users" and "developers" ... I would guess that eventually, most users > > become developers, so then, it's just a matter of "beginning user" vs. > > "power user", and so on. > > > -- > Dr. Hussayn Dabbous > SAXESS Software Design GmbH > Neuenhöfer Allee 125 > 50935 Köln > Telefon: +49-221-56011-0 > Fax: +49-221-56011-20 > E-Mail: [EMAIL PROTECTED] > > > --------------------------------------------------------------------- > Please check that your question has not already been answered in the > FAQ before posting. <http://xml.apache.org/cocoon/faq/index.html> > > To unsubscribe, e-mail: <[EMAIL PROTECTED]> > For additional commands, e-mail: <[EMAIL PROTECTED]> > --------------------------------------------------------------------- Please check that your question has not already been answered in the FAQ before posting. <http://xml.apache.org/cocoon/faq/index.html> To unsubscribe, e-mail: <[EMAIL PROTECTED]> For additional commands, e-mail: <[EMAIL PROTECTED]>
