On Thursday, June 27, 2002, at 02:34 AM, Mikhail Fedotov wrote:
>> After just a few hours of poking around I have decided >> that it will be much simpler for me to simply hand-code >> a whole hat-full of servlets than to try and pull any >> meaning out of Cocoon and it's documentation. > > Two things to mention: > > 1. I've been talking here about documentation in form of > dictionary, where is no structure and long docs, just > complete descriptions of components and their parameters; > it is the quick way to produce complete components > documentation that helps in creation of more complex > documentation. If someone will become interested in > lowering the difficulty of writiting docs (that I've been > talking about), and not just writing another docs page > (that I've been told to do as an response), he could arise > that topic again. Well why don't you check out wiki dictionary effort made with Cocoon? Perhaps you could help build that dictionary. http://www.anyware-tech.com/wikiland/ > 2. About the current docs. They aren't _that_ bad, there is > much of information. But it looks more like an student > work, i.e. it gives impression of work made, but not > optimized for easy understanding and using. Try not to jump to conclusions about why the state of documentation is what it currently is. I made that mistake earlier on this list. ;-) I continue to learn new factors almost every day why producing good docs is difficult in this context. I could add a hundred items to your list. Think of the quality of docs as an indicator of a community's evolution. When more people come forward to help improve existing docs, and contribute new docs, then they will improve. No sooner and no later. If this keeps Cocoon from reaching new audiences, then that's just a result -- it isn't necessarily a problem, just a phase of growth. There is an effort at Apache Forrest to improve underlying documentation architecture. If you don't want to contribute new/revised docs to the Cocoon project, perhaps you'd be interested in supporting that project's architectural efforts? http://xml.apache.org/forrest/ > Here is one > good model usable in too much contexts to mention, and it > is also good in writing docs: I have built a lot of models in my professional life, and I'm not sure I would be so brave as to model open source community dynamics ... ;-) <snip /> > Symptoms - complex webapp, many documents, big hierarchy, > difficulties with all this; some paragraphs about it. I don't agree that a complex webapp is a "symptom" of a problem. I think the problem that Cocoon is trying to solve is complex. As for "many documents," I agree some could be refactored however isn't going to happen until Cocoon migrates to a Forrest architecture (in process already). At the point, many more options to improve the docs structure will become available to us. It just takes time when everyone is a volunteer. We are also making the best of available resources, which at the present time, includes a static web site. Still, I prefer more docs. I don't think there are too "many" docs. I also want to increase the author pool. With difficult, complex subjects like Cocoon, sometimes you need multiple voices to say the same thing, just a bit differently. When you are learning something new, and you have the luxury of buying books, wouldn't you prefer to buy more than one, even if it's about the same topic? > Causes - hierachy isn't structured, components dependence > is out-of-control, bad code reuse, too much amount of > everything, etc; some paragraphs about it. > > Outcome - doing things in a more structured way; some > paragraphs about it. You can have all the structure in the world but you still need writers. IMHO, the hardest part is writing well. If we make writing "easy" by removing so-called architectural obstacles, does that mean we'll automatically have "good" content? I'm not sure about this. Don't get me wrong, I think architectural improvements will help immensely. However, you probably are aware that many authors have the additional challenge of having to write in a non-native language. Regardless of what you think about the docs, I really admire the people who have contributed docs so far. And I'm also excited about the books coming out. > Resources - use of SoC pattern with Cocoon2 as a tool, > transforming the hierarchy into tree with no dependency > between branches; some paragraphs about it. What do you mean by hierarchy? The documentation hierarchy? If you are concerned about 2.1 docs being made available with 2.03 docs, then isn't it enough to note, in very clear and visual terms, what content applies to what branch? The 2.1 docs we have are very good. I think they help users understand some of the great stuff that is going on in the HEAD branch. As long as they are warned, I don't see the problem. Diana --------------------------------------------------------------------- To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, email: [EMAIL PROTECTED]
