cocoon-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Andrew C. Oliver" <acoli...@apache.org>
Subject Re: Giving up! Cocoon too big, slow and confusing
Date Fri, 28 Jun 2002 13:18:40 GMT
> 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.



This should now be moved to cocoon-dev

jakarta.apache.org/poi

the approach is that we document things ;-) and no code is considered 
complete until it has:

1. Full javadoc
2. a howto of some sort (http://jakarta.apache.org/poi/hssf/)
3. a unit test  (* added later -- old code is grandfathered but needs 
the unit test soon)

meaning it can't be released.  

Features authors/submitters are goaded into updating the documentation, 
the culture of the project
is such that most of the committers would refuse to commit code that 
didn't meet these standards.

The project is probably more complicated then cocoon under the covers by 
nature of its problem area,
but the API is very deliberately kept simple.  The architecture is such 
that the details of the file format are hidden
from the user.  Atmoic concerns such as how to deal with a specific 
detail are covered in the org.apache.poi.hssf.records
package.  How to deal with concepts that are not directly represented in 
the file format are contained in org.apache.poi.hssf.model
(adding a row "record" to a sheet for instance, where there is no direct 
representation of a sheet in the file).  This is masked by
a high level API called "usermodel" which lets you work with more 
familiar objects such as "Workbook, Sheet, Row, Cell".  For users who 
need to read in a high performance, low memory-utilization situation, 
they can use org.apache.poi.hssf.eventmodel, but they'll be exposed to 
more details of the file format.

Cocoon tends to fail to achieve any of the three standards above as far 
as javadoc, howtos or unit tests.  Next, there is little or
no effort to mask the complexities, in fact I dare say it increases them 
and bathes the user in them.  Its up to all of us (developers, 
committers, and users alike) to attempt to improve this.  Not take our 
cookies and go home.

Thanks,

-Andy

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.
>
>Derek. 
>
>  
>
>>>>aaldridg@csc.com 28/06/2002 11:51:24 >>>
>>>>        
>>>>
>
>Absolutely! BUT, the point isn't that everyone's dissing Cocoon, it's
>that
>a weakness has been identified, and is being discussed. No need to be
>defensive about it - that's what will drive people to amend the
>situation.
>
>Regards
>
>Anthony Aldridge
>Application Development
>Managed Intranet Hosting
>JPMorganChase
>
>
>
>
>David Crossley <crossley@indexgeo.com.au> on 06/28/2002 10:12:54 AM
>
>Please respond to cocoon-users@xml.apache.org 
>
>To:   cocoon-users@xml.apache.org 
>cc:
>Subject:  Re: Giving up! Cocoon too big, slow and confusing
>
>
>Everyone stop, take a breathe, get a cup of coffee
>and go read "The Cathedral and the Bazaar"
>http://tuxedo.org/~esr/writings/cathedral-bazaar/ 
>or similar writings about how Open Source Software operates.
>It seems that many people here are missing the point.
>
>It amazes me that people have the time to compose email
>to the mailing list to tell us that they are too busy, and
>then have the hide to tell us that documentation is poor.
>
>If each of us add one FAQ to the document collection,
>then the lack will be addressed very quickly. That is OSS.
>If you see an issue, the onus is on you to help remedy that.
>Everyone benefits from the work of each one.
>
>There is no such separate thing as "they, the developers".
>Rather it is "we the community". Anyone who contributes
>a patch (code or doc) is instantly transformed from being
>a "user" into a "developer".
>
>Users use, contributers build projects.
>
>Thanks for raising this topic. I do sympathise with you
>about the complexities and inadequacies. We have all been
>though that and still do. None of us know all of Cocoon
>capabilities and would all benefit from doc contributions.
>Please help.
>--David
>
>
>---------------------------------------------------------------------
>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>
>
>
>---------------------------------------------------------------------
>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>
>
>
>  
>




---------------------------------------------------------------------
To unsubscribe, e-mail: cocoon-dev-unsubscribe@xml.apache.org
For additional commands, email: cocoon-dev-help@xml.apache.org


Mime
View raw message