Better yet, Cocoon already defines 4 "production roles", and add to that the "Cocoon Developer" we get;
1. Content 2. Style 3. Logic 4. Management/Admin 5. Cocoon Developer Note that some docs can always be linked from more than one section. Same thing for a new FAQ section, where there could be multiple "target-role" for each Q and the generated FAQ would compile according to your "role-entrypoint". Niclas On Tuesday 28 January 2003 06:05, Robert Simmons wrote: > 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]> --------------------------------------------------------------------- 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]>
