cocoon-users mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Diana Shannon <shan...@apache.org>
Subject Re: Giving up! Cocoon too big, slow and confusing
Date Thu, 27 Jun 2002 18:42:17 GMT

On Thursday, June 27, 2002, at 11:32  AM, conrad.dcruz@netswirl.com 
wrote:

> Time is the limitation that keeps all the developers from creating good
> docs in pace with the changes in the system.  Occasionally promising 
> open source projects get adopted by a big sponsor corporation which 
> helps to make it easier to cross the chasm.

But this may suggest to users that doc problems can only be solved by 
developers, book authors, and corporations. This isn't necessarily true. 
Or, it doesn't have to be true.

I'll be the first to admit writing Cocoon documentation is difficult. 
You get all excited, start down a path, and -- BAM -- you hit a road 
block. You take a detour, e.g., to read more about Avalon or about Ant. 
Then you come back to continue with your effort. BAM. The cvs HEAD 
branch has changed. What worked yesterday doesn't work today. Did you do 
something wrong? Maybe. To be safe (who wants to confuse future users) 
you start over. BAM. You can't figure out the meaning of a component 
parameter. It's not even defined in the source code. Need to run it by 
Vadim on cocoon-users. BAM. etc. etc. etc.

Sounds pretty frustrating, eh? Well..... the reward is you learn a 
*ton,* and you will advance your abilities as a Cocoon user unlike any 
other available option. For example, I just finished a new How-To, but 
now I feel I can write a How-To on about ten other Cocoon topics, just 
from the knowledge I gained in this single writing experience. Granted, 
this kind of job isn't for everyone, but I don't know of a better way to 
learn for intermediate users. And in my short experience, developers 
have been unbelievably responsive to my technical questions. What a 
great learning opportunity for the taking!

I think intermediate Cocoon users can make a *big* difference with docs, 
if they can find the time to write. Do users realize this? I personally 
didn't know I could even help out with an open source project with doc 
writing until very recently -- and I've been using Cocoon since version 
1.0. I know, it's hard to find the time to do lots of things, but if you 
are invested in Cocoon, you may really enjoy and benefit from the 
writing experience -- no matter how small a contribution you make.  I 
also believe it's important for *users* to write some docs because they 
are in a better position to understand the challenges other users face. 
This won't solve the problem overnight, but it's has a positive feedback 
loop, i.e. more docs -> more knowledge -> more authors w/knowledge -> 
more docs ...

I know this response doesn't satisfy all of the concerns raised in this 
thread. Nevertheless, if users want to write docs, please check out the 
How-Tos that are available for documentation at 
http://xml.apache.org/cocoon/howto/ . If you want to work on existing 
docs, contact me to talk about it. Interested in editing? There's a lot 
for you to do. Want to work on architectural doc issues? Check out 
Forrest. http://xml.apache.org/forrest/  If you don't have time to 
provide structured text for your work, simply post the content to this 
list. Given time, I'm sure someone will find a way to migrate useful 
content to an official Cocoon document. Quality open source docs may 
take time, and the results may seem incremental at first, but that 
doesn't mean it can't or it won't happen... it may just not happen on 
*your* time frame.

-- Diana



---------------------------------------------------------------------
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