Return-Path: 
 <cocoon-users-return-45507-apmail-xml-cocoon-users-archive=xml.apache.org@xml.apache.org>
Delivered-To: apmail-xml-cocoon-users-archive@xml.apache.org
Received: (qmail 59974 invoked by uid 500); 27 Jan 2003 19:07:17 -0000
Mailing-List: contact cocoon-users-help@xml.apache.org; run by ezmlm
Precedence: bulk
list-help: <mailto:cocoon-users-help@xml.apache.org>
list-unsubscribe: <mailto:cocoon-users-unsubscribe@xml.apache.org>
list-post: <mailto:cocoon-users@xml.apache.org>
Reply-To: cocoon-users@xml.apache.org
Delivered-To: mailing list cocoon-users@xml.apache.org
Received: (qmail 59962 invoked from network); 27 Jan 2003 19:07:17 -0000
Date: Mon, 27 Jan 2003 14:03:02 -0500 (EST)
From: Tony Collen <tcollen@neuagency.com>
To: <cocoon-users@xml.apache.org>
Subject: Re: proposal: "The Newbies Competence Center"
In-Reply-To: <3E357D04.3010207@saxess.com>
Message-ID: <20030127135133.Y23827-100000@neuagency.com>
MIME-Version: 1.0
Content-Type: TEXT/PLAIN; charset=US-ASCII
X-Spam-Rating: daedalus.apache.org 1.6.2 0/1000/N

On Mon, 27 Jan 2003, SAXESS - Hussayn Dabbous wrote:

<snip/>

> o There was an idea to redesign the cocoon documentation entry page
>    and provide chapters like:
>
>    1) First steps
>    2) User's Manual
>    3) User's Reference
>    4) Architecture
>    5) Developer's Guide

This is good. HOWEVER, occasionally the line between "user" and
"developer" gets blurred, especially when a user realizes they need to
develop a custom component.

All too often, I've gone to the developer section looking for information
that was actually in the user guide, and vice versa.

One thing I'd like to see, at least for the "production" docs, is to have
the API Javadocs up front and center.

I may have mentioned this one last time the issue of docs came up, but
here's another thing that confused me:

(Taken from xml.apache.org/cocoon/):

Documentation
  Introduction
  Installing
  Overview
  User Guide
  Dev Guide
  Tutorials
  FAQs
  How-Tos
  Performance
  Snippets
  ToC

Ok, Introduction and Installing are good, and Overview I can understand.
Perhaps these are a little out of order.  Now the problem is, where do I
go to in order to find out how to strip out my sitemap?  There's a User
guide, Tutorials, FAQs, and How-to's, which all sort of could be the same
thing.. especially "Tutorials" and "How-tos".  Snippets could also be
considered how-to, but also probably tutorial.  The same goes for the
"performance" section.

Basically, what I see needs to be done, is we need all of this info
consolidated into one place.

Remember, the docs are for the users, and unfortunately, the developers
might have a different idea about how the information "should" be
categorized.    Or maybe our problem is making the distinction between
"users" and "developers" ...  I would guess that eventually, most users
become developers, so then, it's just a matter of "beginning user" vs.
"power user", and so on.



Tony

--
Cocoon: Internet Glue (A Cocoon Weblog)
http://manero.org/weblog/



---------------------------------------------------------------------
Please check that your question  has not already been answered in the
FAQ before posting.     <http://xml.apache.org/cocoon/faq/index.html>

To unsubscribe, e-mail:     <cocoon-users-unsubscribe@xml.apache.org>
For additional commands, e-mail:   <cocoon-users-help@xml.apache.org>