cocoon-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Gerhard Froehlich" <>
Subject RE: ToC, SoC, and Views
Date Sat, 05 Jan 2002 16:40:52 GMT

>With respect to the new outline for documentation I would like to suggest 
>that we leverage the concept of "views" and present the same content in 
>different ways for different audiences.  As I see it, there are 5 audiences 
>for the documentation.
>Four of these (Manager, Logician, Author?, Stylist) are described by the 
>"pyramid model of web contracts" which, assuming that we have remained true 
>to this vision, are still the backbone of the Cocoon concept of web 
>publishing.(*)  The fifth audience are the multi-talented individuals, who 
>I imagine actually make up most of the Cocoon adopters at this point, who 
>are trying to introduce a Cocoon-based solution and are doing everything 
>The new ToC currently in CVS feels very "O'Reilly-ish", and in my opinion 
>is oriented at the multi-talented audience, possibly focusing on the 
>Manager and the Logician.

That's right. I went the classic way and oriented me at the existing
user documentation in the Apache Group.

Hmm how about using this SoC approach to organize our homepage?

>On the list the term "SoC" keeps being raised either in support or in 
>rebuttal of a proposal.  One thing that rarely seems to happen is the 
>identification and elaboration of these Concerns.
><grumble>It's all well and good to say "Nope, SoC makes this a bad idea", 
>but it would be nice to know what concerns are being overlapped and why the 
>concern exists at all.  Some heuristics that say "For X, think like a 
>manager.  For Y and Z, think like a  consumer..." would at times make 
>things a lot clearer.</grumble>
>Given the importance of SoC, I think the Cocoon documentation should 
>reflect the different Concerns that form the basis of Cocoon.  Using views 
>and hyperlinking it should be possible to use the same, or very similar, 
>source materials and arrange them appropriately.

Hmm I don't know. Personally I'm used to read technical handbooks studying
the ToC and jump to the section I searched.
The main Problem now is that people don't find the correct information in
our docs. I think people are used searching by topic, like:
"Shit Cocoon leaks, ahh but there is a chapter "Tuning" in the ToC, lets
have a look".

>Hopefully this didn't come across too negatively.  That wasn't the intent.

No way dude, constructive critics always welcome!

>   It's just that sometimes things seem to focus so much on low-level issues 
>that I start to wonder if Cocoon still has an overall vision that is being 
>shared collectively.  Now that Cocoon2 has been released, isn't it time to 
>focus a little on how to use it?  Thus far the focus is on how to construct 
>a SiteMap and while the SiteMap is important, I'm left to wonder if it has 
>completely supplanted the original Cocoon vision.

Jason. Can you post a proposal for the SoC approach. Must not be totally 
complete. I can book it in and then we can easily compare those two approaches.

At the end the community will decide!



That must be wonderful! I don't understand it at all.

To unsubscribe, e-mail:
For additional commands, email:

View raw message