Hi! > 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. 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. Here is one good model usable in too much contexts to mention, and it is also good in writing docs: *** S.C.O.R.E. Symptoms/State - that problems look like, current state Causes - that are causes of those problems (in the past?) Outcome - that state we want to reach after changes Resources - that we can use to do that Effects - that is benefit of a new state and that are drawbacks. *** For example, at the most general level, SoC pattern and dependencies problem: *** Symptoms - complex webapp, many documents, big hierarchy, difficulties with all this; some paragraphs about it. 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. Resources - use of SoC pattern with Cocoon2 as a tool, transforming the hierarchy into tree with no dependency between branches; some paragraphs about it. Effects - minimum update/modification time compared to starting state, but requirement to invest additional time in study of tools, at least; some paragraphs about it. *** Well, this application of S.C.O.R.E. is quick and dirty, I've just tried to do it fast. But this model really do worth in terms of understanding. Positive side of effects is that drive us to get outcome, and negative side it that could made us to change our plans. Outcome by itself doesn't mean anything. It could be used to refactor current documentation. Even matchers can be put into SCORE - that we had and weren't satisfied with (well, we had servlets-like url mapping), that state we want (maybe it's current cocoon url mapping mechanism? well, I don't think it's ideal, but that's me), that is preventing us from moving (don't know, except that there were no matchers code before it was written), that resources we have to help us move (all possible ways to map an url into processing code and ways to implement them), and that effects we'll have after we reach our state. Effects are benefits and disadvantages of using matchers. For me, it is a bit too low-level instrument, but again, that's me. This model requires thinking abilities, but pays off. The best of all, it helps to detect defect ideas. And it is reasy to use. > complete lack of consistency between different > components (i.e. functional code, non-functional > examples, unbuildable documentation and a website > that doesn't match up with any single > released version of the project). That's a very familiar pain. But I don't think there is an immediate solution for it in open source development. Mikhail --------------------------------------------------------------------- To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, email: [EMAIL PROTECTED]
