Tony Collen wrote:
On Mon, 27 Jan 2003, SAXESS - Hussayn Dabbous wrote: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.
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.
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]>
