cocoon-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Sylvain Wallez <sylv...@apache.org>
Subject Re: Improving portals block [was: Re: [VOTE] Status of Portal blocks]
Date Thu, 26 Aug 2004 13:55:56 GMT
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 }


Mime
View raw message