ToC, SoC, and Views

[Jason Foster <ja...@uwaterloo.ca>]

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 
themselves.

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.

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.

Hopefully this didn't come across too negatively.  That wasn't the intent.
   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 Foster

(*) The Cocoon documentation states:

> The model that Cocoon adopts is the "pyramid model of web contracts" which 
> is outlined in the picture below and is composed by four different working 
> contexts (the rectangles)
>
> *	Management - The people that decide what the site should contain, how 
> it should behave and how it should appear
> *	Content - The people responsible for writing, owning and managing the 
> site content. This context may contain several sub-contexts - one for each 
> language used to express page content.
> *	Logic - The people responsible for integration with dynamic content 
> generation technologies and database systems.
> *	Style - The people responsible for information presentation, look & 
> feel, site graphics and its maintenance.
>
> and five contracts (the lines)
>
> *	management - content
> *	management - logic
> *	management - style
> *	content - logic
> *	content - style
>
> Note that there is no logic - style contract. Cocoon aims to provide both 
> software and guidelines to allow you to remove such a contract.

If I approach this model from the perspective of someone new to web 
publishing (eg. I used to do all of my web pages in DreamWeaver and host on 
GeoCity.) the current documentation and discussion does not make at all 
clear what the contracts actually mean, what the guidelines for removing 
the logic-style contract are, and in general how Cocoon *thinks*.  In my 
opinion this is what is needed, now that I can download Tomcat and Cocoon 
and be ready to go in 10 minutes!  While the examples that come with Cocoon 
show you *how* to do certain things, they don't go into the *why* much at 
all.


---------------------------------------------------------------------
To unsubscribe, e-mail: cocoon-dev-unsubscribe@xml.apache.org
For additional commands, email: cocoon-dev-help@xml.apache.org

RE: ToC, SoC, and Views

[Gerhard Froehlich <g-...@gmx.de>]

Jason,

>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 
>themselves.
>
>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.

<thought>
Hmm how about using this SoC approach to organize our homepage?
</thought>

>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!

  Gerhard

<skip/>

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


---------------------------------------------------------------------
To unsubscribe, e-mail: cocoon-dev-unsubscribe@xml.apache.org
For additional commands, email: cocoon-dev-help@xml.apache.org