On Thursday, June 27, 2002, at 11:32 AM, [EMAIL PROTECTED] 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: <[EMAIL PROTECTED]> For additional commands, e-mail: <[EMAIL PROTECTED]>
