to create some example solutions.
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]>
