cocoon-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Mikhail Fedotov" <mikh...@kittown.com>
Subject docs & misc
Date Thu, 27 Jun 2002 06:34:39 GMT
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: cocoon-dev-unsubscribe@xml.apache.org
For additional commands, email: cocoon-dev-help@xml.apache.org


Mime
View raw message