cocoon-users mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Derek Hohls" <DHo...@csir.co.za>
Subject Re: proposal: "The Newbies Competence Center"
Date Tue, 28 Jan 2003 07:00:45 GMT
I think that Miles' outline below reflects a very good way
of organising the primary Cocoon site.  I am not sure that
it is completely appropriate for new users (yes, I still 
think there is a distinction between a user and a 'hard core'
developer - see later replies).  

The "First Steps" chapter listed below is the one that needs
some thought and attention.  My feeling is that we need to
focus on the problems that needs to be solved, rather than
a lengthy description of what is *possible* with Cocoon.  
This should be difficult to draw up; there are many common 
problems for web developers and it should not be that hard
to create some example solutions.
 
Comes back to what I am comfortable with "learning by seeing
and then doing"... the light of in-depth understanding usually
dawns a little later on.

>>> miles@pcextremist.com 27/01/2003 10:10:48 >>>
Tony Collen wrote:

>On Mon, 27 Jan 2003, SAXESS - Hussayn Dabbous wrote:
>
>  
>
>>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.
>
I totally agree.  In fact, this is an item that I took issue with in 
Lajos and Jeremy's book: which "Generators" section should I be looking

in?  I also don't know that a quick reference and a manual must be 
distinct items.  For a printed book, this makes a lot of sense.  But
the 
web is inherently a quick reference -- bouncing from relevant topic to

relevant topic.  This is an area where I think the existing 
documentation (for some components) shines.  If you take a look at the

Request XSP logicsheet 
(http://xml.apache.org/cocoon/userdocs/xsp/request.html), this is an 
example of what I mean.  If the page simply had quick, in-page links to

description, usage, examples, and quick reference, you would be done. 
A 
user looking up information says, "Hmmm, I know I want to use a 
serializer so I'll go to the serializer section."  From there, they can

select if they want an example, an API lookup, etc.  Quick references 
exist because no one wants to haul around five hundred page books.  But

if you are on the web, you already have access to a million page book. 

The same rules don't apply.

However, I think the above list has merit if you clearly define what 
"development" is.  I tend to think that *anyone* who installs Cocoon
and 
edits something to be a developer rather than a user.  The users, in my

mind, are the folks using the web browser.  There are, however, 
different classes of developer.  For example, if you write an XSP 
document, you've in essense written a generator.  No, they didn't call

javac themselves, but it's only slightly different.  The difference 
mainly lies in its relative ease, not in the intent.  If you set up a 
pipeline in the sitemap, what are you if not a developer assembling 
components together?

On the other hand, making changes to the Flow engine, the cache store,

the sitemap parser, etc. are definitely different from writing your own

transformer.  The distinction in the documentation should be "here are

things you can do for your own benefit that affect no one else" and 
"here are things that fundamentally affect the requirements for other 
components."

For example:

1) Architecture Overview/Primer/First Steps
  a) Why Cocoon exists
  b) Quick start installation
  c) Hello World (XSP document going through a simple transformer and 
serializing to HTML)
  d) Very brief introduction to sitemaps, generators, etc. by
explaining 
Hello World

2) The Cocoon servlet
  a) Installation instructions
    i) Tomcat
    ii) Jetty
    iii) JBoss
    iv) etc.
  b) Web app layout
    i) Configuration locations (logkit.xconf, cocoon.xconf, etc.)
      a. cocoon.xconf
      b. logkit.xconf
      c. etc.
    ii) Library locations and itemization
      a. lib
      b. classes
    iii) Other

3) Architecture in depth
  a) Generators
    i) What they are and why they exist
    ii) Listing of existing generators, their usage, and examples
    iii) How to write a custom generator (with a reference to XSP)
  b) Transformers
    i) What they are and why they exist
    ii) Listing of existing transformers, their usage, and examples
    iii) How to write a custom transformer

  ...repeat this model for the other major components...

4) Best practices by use case

5) Advanced Architecture
  a) Cache store
    i) How the existing implementation(s) work
    ii) Basic steps to implement your own
  b) Sitemap logic
    i) How the existing implementation(s) work
    ii) Basic steps to implement your own
  c) Flow
    i) How the existing implementation works
    ii) -- Heh, I don't know that implementing your own is less than a

novel --

6) Appendixes
  a) Avalon references
  b) W3C references

--------

The idea here that the first hooks the newcomer and gives them a taste

of what's possible.  The second helps them get it going on their 
machine.  The third describes how everything works.  The fourth builds

upon everything else to help in working, production environments.  The

fifth is the "graduate degree" when someone is ready for committer 
status.  The last is simply relevant reference material all put
together 
in one place (it's assumed that the rest of the documentation would
have 
topic-specific references to parts of these).

Thoughts?

- Miles



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



-- 
This message has been scanned for viruses and dangerous content by 
MailScanner, and is believed to be clean.

"The CSIR exercises no editorial control over E-mail messages and/or
attachments thereto/links referred to therein originating in the
organisation and the views in this message/attachments thereto are
therefore not necessarily those of the CSIR and/or its employees.  
The sender of this e-mail is, moreover, in terms of the CSIR's Conditions
of Service, subject to compliance with the CSIR's internal E-mail and 
Internet Policy."


Mime
View raw message