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.
>>> [EMAIL PROTECTED] 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: <[EMAIL PROTECTED]>
For additional commands, e-mail: <[EMAIL PROTECTED]>
--
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."
