cocoon-users mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Luca Morandini" <luca.morandi...@tin.it>
Subject RE: Giving up! Cocoon too big, slow and confusing
Date Fri, 28 Jun 2002 17:40:40 GMT
>           o The entry "How do I hide "cocoon" in the URL's once I
>             integrate using mod_jk as shown above?" could be improved,
>             as I did not find it helpful. I could make specific
>             suggestions, but I think that would be outside the context
>             of this list.

Ok, ok, I've just improved it, and it'll be posted very soon by Diana.

BTW, does anyone know whether setting "/cocoon" as default Docbase works for servlets containers
other than Tomcat ?

Best regards,

--------------------------------------------- 
               Luca Morandini 
               GIS Consultant 
              lmorandini@ieee.org 
http://utenti.tripod.it/lmorandini/index.html 
---------------------------------------------
 

> -----Original Message-----
> From: Liam Morley [mailto:lmorley@gdc.wpi.edu]
> Sent: Friday, June 28, 2002 7:27 PM
> To: cocoon-users@xml.apache.org
> Subject: Re: Giving up! Cocoon too big, slow and confusing
> 
> 
> comments inline.
> 
> Nicola Ken Barozzi wrote:
> 
> > Derek Hohls wrote:
> >
> >> Yes!!  I think I can finally add my 0.2c here - "we as a community" 
> >> have agreed that the docs are
> >> not ideal and that that (along with maybe some other
> >> more technical design issues) creates a steep learning
> >> curve - if we agree on a way forward to improve it, then no 
> >> defensiveness is required: NOTE that no one
> >> has criticised Cocoon per se (or what it is trying to do);
> >> only the way that it is *perceived* - as a suggestion; can anyone 
> >> point to concrete examples of complex, but well-
> >> documented, easy-to-learn open-source projects =>
> >> lets adopt their approach(es) and see where/how we
> >> can change what we have (or add where there are gaps)
> >> to get to a better place.
> >
> I think Derek's idea is a very good one. We are a complex open-source 
> project; let's emulate a complex, well-documented open-source project. 
> Yes, we are an open source community; in my eyes, one of the best ways 
> for that community to expand is to open our doors (through better 
> documentation) so that the learning curve is less steep and more people 
> are able to jump on board. I honestly think I might be writing code for 
> Cocoon if I had an idea from the documentation where it was headed.
> 
> >
> > We need simple examples, simple use cases, all using the terminology
> > that _you users_ look for in the documentation.
> >
> > What would be really of help are *concrete* examples.
> >
> > It's easy to tell us: when you read the Cocoon documentation, you are 
> > looking for something specific... what is it?
> >
> actually, there are a lot of times when I'm looking for documentation to 
> get a general feel for an issue. Often times the concrete examples don't 
> communicate /why/ I would want to use something, or in what context it 
> might be used.  The only Cocoon how-to (other than the five how-to's on 
> how to write code/documentation for Cocoon, or the 3rd party how-tos) I 
> saw was on XMLForm. I've been using Cocoon for a year, and I haven't 
> used XMLForm once. I really have no gauge (other than the mailing list) 
> on who's using what or what actually needs to be documented.
> I also agree that we need to move beyond simply saying "the 
> documentation needs to be improved" and start talking about how to 
> improve it. I thought about what I was looking for from Cocoon and what 
> I saw as lacking on the website, and came up with the following:
> 
>     * Best Practice(s) Tutorials. There are probably multiple different
>       equally good ways of doing a lot of things with Cocoon, I
>       certainly think that a best practice tutorial is necessary.
>     * Currently, the front page of the Dev Guide says "Here will soon
>       appear an overview of the developer perspective."
>     * Users's Section:
>           o Concepts section:
>                 + On the overview page, I saw several things that seemed
>                   outdated, including:
>                       # In "Apache Cocoon Configuration", cocoon.xconf
>                         has moved
>                       # In "Apache Cocoon Work Area", the log format has
>                         changed since that was written.
>                       # In "Use with Tomcat", we've had binaries for a
>                         while now; we shouldn't be pushing users towards
>                         CVS unless they're experiencing a problem with
>                         the current packaged binary/source or they want
>                         the bleeding edge.
>                 + On the sitemap page, this looks good, but I remember a
>                   thread mentioning the need for a complete DTD to be
>                   outlined; is that it, or are there other things that
>                   need to be added? I found some good documentation at
>                   <http://outerthought.net/sitemap/>, perhaps this could
>                   be integrated or referred to.
>                 + I liked the fact that the "Views" page offered a
>                   motivation section; this explains why I should use a
>                   certain component. I think more doc pages should have
>                   a section like this. (I thought views were only used
>                   for debugging? it looks like I'm wrong, and I may be
>                   more inclined to look into views in the future.)
>                 + In the "MRUMemoryStore" section, doesn't
>                   "Implementation" belong in a developer's section, not
>                   a user's section? As a user, I don't think I should
>                   know how it's implemented to use it.
>                 + I find the "Persistence" doc a bit hard to understand
>                   (parts of it are broken english). I'm also not sure
>                   how it relates to the "Caching" section, or how it
>                   differs. I think this section could use some more
>                   documentation.
>                 + I think the StoreJanitor section would benefit greatly
>                   from a "Motivation" paragraph. At least to me, it's
>                   not immediately apparent what it's for.
>                 + I think the databases section is great; our project,
>                   however, wrote a transformer that uses JDBC but does
>                   not involve the Cocoon SQLTransformer. I suppose that
>                   option could be added if desired. (The SQLTransformer
>                   part does mention writing a custom transformer, but I
>                   think the option could be added as its own section of
>                   the page.)
>           o Generators: I realize that certain classes like
>             "PhpGenerator" are optional and aren't much of a priority as
>             far as documentation goes, but I think the text "????."
>             could be cleaned up a bit. On the whole, however, the
>             Generator section has been greatly improved since the last
>             time I saw it.
>           o Transformers: This has also greatly improved since the last
>             time I saw it. From looking at the LDAP Transformer,
>             however, it's hard for me to understand how to integrate it
>             into my existing codebase, or whether I'll have to write
>             customized JNDI code. I'd love it if the LDAP transformer
>             page was cleaned up.
>           o Serializers: this section could use an update. Again, the
>             text "????." shouldn't be seen.
>           o The XSP Overview needs updating.
>     * FAQ's:
>           o The entry "How do I integrate Apache Server and Cocoon?"
>             needs updating, as there are several connectors being used.
>             When Tomcat 4.1.3 is no longer beta, then Coyote will be the
>             default connector, which will introduce JK2; this is bound
>             to confuse a lot of people unless the documentation is updated.
>           o The entry "How do I hide "cocoon" in the URL's once I
>             integrate using mod_jk as shown above?" could be improved,
>             as I did not find it helpful. I could make specific
>             suggestions, but I think that would be outside the context
>             of this list.
>           o I think an entry "When should I use CVS?" should be added to
>             the CVS FAQ section. Not all users need it, and not
>             everybody knows if they should use it or not.
>           o I think an entry concerning the sitemap should be made in
>             the "Configuring Cocoon" section on sitemap configuration
>             that gives a *brief* overview and points towards other
>             sitemap docs. Although we have great sitemap documentation
>             elsewhere on the website, people will still come to the FAQ
>             looking for it.
>           o I tried the debugging FAQ and got an exception (although I
>             can post that as a seperate email).
>           o In the Aggregators section, I would benefit from an entry
>             entitled "Why would I use an aggregator?" discussing some
>             common examples of aggregator usage. 
> 
> I apologize for the length and realize that this subject may be better 
> served if it moves off the users list, but I wanted to put some of this 
> on the table and put my money where my mouth is.
> 
> Liam Morley
> 
> 
> ---------------------------------------------------------------------
> 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:     <cocoon-users-unsubscribe@xml.apache.org>
> For additional commands, e-mail:   <cocoon-users-help@xml.apache.org>
> 

---------------------------------------------------------------------
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:     <cocoon-users-unsubscribe@xml.apache.org>
For additional commands, e-mail:   <cocoon-users-help@xml.apache.org>


Mime
View raw message