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