Return-Path: Delivered-To: apmail-cocoon-dev-archive@www.apache.org Received: (qmail 62307 invoked from network); 6 Nov 2006 06:11:35 -0000 Received: from hermes.apache.org (HELO mail.apache.org) (140.211.11.2) by minotaur.apache.org with SMTP; 6 Nov 2006 06:11:35 -0000 Received: (qmail 46065 invoked by uid 500); 6 Nov 2006 06:11:46 -0000 Delivered-To: apmail-cocoon-dev-archive@cocoon.apache.org Received: (qmail 45741 invoked by uid 500); 6 Nov 2006 06:11:44 -0000 Mailing-List: contact dev-help@cocoon.apache.org; run by ezmlm Precedence: bulk list-help: list-unsubscribe: List-Post: Reply-To: dev@cocoon.apache.org List-Id: Delivered-To: mailing list dev@cocoon.apache.org Delivered-To: moderator for dev@cocoon.apache.org Received: (qmail 51868 invoked by uid 99); 5 Nov 2006 20:18:52 -0000 X-ASF-Spam-Status: No, hits=2.0 required=10.0 tests=HTML_MESSAGE X-Spam-Check-By: apache.org Received-SPF: neutral (herse.apache.org: local policy) From: Mike Robinson Organization: Sundial Services To: dev@cocoon.apache.org Subject: So, where's the =users= guide? Where's the intro? Date: Sun, 5 Nov 2006 15:18:17 -0500 User-Agent: KMail/1.9.1 MIME-Version: 1.0 Content-Type: multipart/alternative; boundary="Boundary-00=_JckTF6jrASdDTpy" Content-Transfer-Encoding: 7bit Content-Disposition: inline Message-Id: <200611051518.17806.miker@sundialservices.com> X-Virus-Checked: Checked by ClamAV on apache.org --Boundary-00=_JckTF6jrASdDTpy Content-Type: text/plain; charset="us-ascii" Content-Transfer-Encoding: 7bit Sigh... In the opening pages of the Cocoon documentation web-site, there are some very excellent promises that you'll talk to "users" and to "developers." Furthermore, you say that "users" don't need to plunge deeply into Java-land to know how to use and produce content with Cocoon. But then, after having given a nodding-glance to the non-developer, the documents promptly plunge headfirst into an intricate and seemingly free-association based tangle of details where "one thing leads to another and another." Your documents talk all about Cocoon in all of its messy developer-oriented detail, without fulfilling the original promise made to the "user." In http://cocoon.apache.org/2.1/userdocs/index.html, you said ... If you are a usual user, then you can use Cocoon without ever coding Java or knowing how exactly servlet containers work. If you become an experienced user of Cocoon you might want to tweak and tune your application. Therefore it is helpful to know Java and some basics of servlet containers. However, if you want to develop with Cocoon (building own components to extend Cocoon for example), then you need to program Java. So, we split up this description into two sections: one for users and one for developers. As far as I can readily tell, this is the first and last point anywhere in the docs where the slightest thought is given to "without ever coding Java or knowing exactly how servlet containers work" (this last bit having casually slipped a mouthful like "servlet container" with nary a second thought as to how unintelligible that might actually be). So I'm still scuffing around looking for "how do I use Cocoon? How much can I do without having to know 'how' it works?" There isn't, yet, a clearly-defined track that I can see through this jumble of documentation-objects that does not plunge headlong, again and again and again, through a rather-giddy expose of extremely geeky subject matter. Mind you, I happen to be a seasoned developer, so it's not that I don't understand what has been written here. But, the promise made to fully half of the potential user-base who might be reading this stuff, simply isn't addressed (imho) beyond that opening page. --Boundary-00=_JckTF6jrASdDTpy Content-Type: text/html; charset="us-ascii" Content-Transfer-Encoding: 7bit

Sigh...

In the opening pages of the Cocoon documentation web-site, there are some very excellent promises that you'll talk to "users" and to "developers." Furthermore, you say that "users" don't need to plunge deeply into Java-land to know how to use and produce content with Cocoon.

But then, after having given a nodding-glance to the non-developer, the documents promptly plunge headfirst into an intricate and seemingly free-association based tangle of details where "one thing leads to another and another." Your documents talk all about Cocoon in all of its messy developer-oriented detail, without fulfilling the original promise made to the "user."

In http://cocoon.apache.org/2.1/userdocs/index.html, you said ...

If you are a usual user, then you can use Cocoon without ever coding Java or knowing how exactly servlet containers work. If you become an experienced user of Cocoon you might want to tweak and tune your application. Therefore it is helpful to know Java and some basics of servlet containers.

However, if you want to develop with Cocoon (building own components to extend Cocoon for example), then you need to program Java. So, we split up this description into two sections: one for users and one for developers.

As far as I can readily tell, this is the first and last point anywhere in the docs where the slightest thought is given to "without ever coding Java or knowing exactly how servlet containers work" (this last bit having casually slipped a mouthful like "servlet container" with nary a second thought as to how unintelligible that might actually be).

So I'm still scuffing around looking for "how do I use Cocoon? How much can I do without having to know 'how' it works?"

There isn't, yet, a clearly-defined track that I can see through this jumble of documentation-objects that does not plunge headlong, again and again and again, through a rather-giddy expose of extremely geeky subject matter.

Mind you, I happen to be a seasoned developer, so it's not that I don't understand what has been written here. But, the promise made to fully half of the potential user-base who might be reading this stuff, simply isn't addressed (imho) beyond that opening page.

--Boundary-00=_JckTF6jrASdDTpy--