Re: Improving portals block [was: Re: [VOTE] Status of Portal blocks]

[Ralph Goers <Ra...@dslextreme.com>]

Carsten Ziegeler said:

> Now, let me give the "dumb open source answer" (this is not
> targetted at you, Ralph). Cocoon and the portal block are
> open source. So, if something is missing or not the way you
> like it etc., you can change it. This is usually how open
> source works: someone has an itch and starts scratching
> it - perhaps over time others help scratching ;)
>
> So, comming back to the topic at hand: yes, the docs about
> the portal are not perfect and I can only hope that they
> will improve over time.
> Documentation can grow in small steps: Each time someone
> finds that an information is missing in the docs, she can
> contribute a small patch with just this piece of information.
> This only takes some minutes to do (ok, first you have to
> find the information, but once you got it, providing the
> patch is simple).
> If something is unclear in the docs, ask and the docs
> can be made more clear. And so on.
>
> As more and more people are actually using the portal,
> I have the hope that the docs will improve as well.
>

Believe me, I am familiar with this philosophy.  With most Cocoon
components I really don't have much of a problem with the doc. Most
generators, input modules, etc. have enough Javadoc that you can get what
you need from them.  However, the Portal is a large piece of work and it
can be difficult to figure out just what is happening just by looking at
the code.

 I just took a look at the existing doc and it is OK from a 30,000 foot
view.  The problem is when you actually want to use it and you need to
have it behave just slightly differently you need a little more than just
samples to clone.  All that is missing, from my point of view, is a sort
of sequence diagram that shows how a request gets processed through the
framework.  That would be an immense help.  I'd be happy to write it -
but since I don't yet have the understanding to do that it wouldn't be of
much use to anybody.

Ralph