cocoon-docs mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Miles Elam <mi...@pcextremist.com>
Subject Re: proposal: "The Newbies Competence Center"
Date Mon, 27 Jan 2003 20:10:48 GMT
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



Mime
View raw message