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

[Carsten Ziegeler <cz...@s-und-n.de>]

Ralph Goers wrote:
> 
> 1. The old portal contains at least a minimal amount of 
> portal administration functionality. The new portal contains nothing.
Unfortunately this is true, but I'm really sure that soon
some tools for the new portal will appear and with a little
luck a real "portal tool" community will be established
improving this area.

> 2. The new portal documentation is poor. We are currently 
> trying to figure out how to heavily leverage it and there is 
> no documentation on Aspects, rendering, when and how the 
> various stylesheets are invoked and how they 
> relate to the various portal.xml files.   Currently, the only 
> way to figure 
> it out is to modify the sample portal in a piecemeal fashion 
> and see what happens - and then look at the code to figure 
> out why.  This takes a LONG time. In short, the portal 
> documentation on the web site needs to be improved to discuss 
> some of the internals (especially since there are no 
> administration tools). 
> 
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.

Carsten 

Carsten Ziegeler 
Open Source Group, S&N AG
http://www.s-und-n.de
http://www.osoco.net/weblogs/rael/

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

[Carsten Ziegeler <cz...@apache.org>]

Sylvain Wallez wrote:
> 
> Mmmh... I'm not sure the "scratch an itch" pattern applies to docs.
> 
> With code, you start scratching because you need a new 
> feature, and since you need to write that new feature for 
> your own need, you can with not much additional cost share it 
> with others.
> 
> With docs that lack the information you're need, you will dig 
> in the code and samples to find that information, and once 
> you've found the answer, your problem is solved. Writing docs 
> requires the extra effort of taking the time to share your 
> findings with the community.
Exactly and my point is that this extra time is really, really
not very much. You can simply write down your problem and the
solution in a language that somehow looks like english (that's
the way I write most times...) and file the patch. With this
you help others and someday someone will help you. So it 
will pay back.

> 
> That certainly explains why our docs are so bad compared to 
> all the features Cocoon provides.
> 
:)

Carsten

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

[Sylvain Wallez <sy...@apache.org>]

Carsten Ziegeler wrote:

>Ralph Goers wrote:
>  
>
>>1. The old portal contains at least a minimal amount of 
>>portal administration functionality. The new portal contains nothing.
>>    
>>
>Unfortunately this is true, but I'm really sure that soon
>some tools for the new portal will appear and with a little
>luck a real "portal tool" community will be established
>improving this area.
>
>  
>
>>2. The new portal documentation is poor. We are currently 
>>trying to figure out how to heavily leverage it and there is 
>>no documentation on Aspects, rendering, when and how the 
>>various stylesheets are invoked and how they 
>>relate to the various portal.xml files.   Currently, the only 
>>way to figure 
>>it out is to modify the sample portal in a piecemeal fashion 
>>and see what happens - and then look at the code to figure 
>>out why.  This takes a LONG time. In short, the portal 
>>documentation on the web site needs to be improved to discuss 
>>some of the internals (especially since there are no 
>>administration tools). 
>>
>>    
>>
>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.
>  
>

Mmmh... I'm not sure the "scratch an itch" pattern applies to docs.

With code, you start scratching because you need a new feature, and 
since you need to write that new feature for your own need, you can with 
not much additional cost share it with others.

With docs that lack the information you're need, you will dig in the 
code and samples to find that information, and once you've found the 
answer, your problem is solved. Writing docs requires the extra effort 
of taking the time to share your findings with the community.

That certainly explains why our docs are so bad compared to all the 
features Cocoon provides.

Sylvain

-- 
Sylvain Wallez                                  Anyware Technologies
http://www.apache.org/~sylvain           http://www.anyware-tech.com
{ XML, Java, Cocoon, OpenSource }*{ Training, Consulting, Projects }

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