cocoon-users mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Naquin, Beth" <>
Subject Ideas/suggestions for docs + offer 2 help (kinda long)
Date Fri, 28 Jun 2002 22:30:26 GMT

Disclaimer:  I am new to cocoon & might not be the right/best person to be
trying to contribute this kind of thing, but here it goes anyway ...

I had some ideas for documents and/or changes to existing documents that I
think would have helped me when I first started.
It would be nice if every 'component' had a page in the user guide, which is
I think what has been started but some just don't have docs yet. [Its REALLY
hard to find anything in a mailing list, if you don't know what to search
for (like a component name or term).  If I have a basic functional
description of each 'component' or 'area' then, if it looks like it might be
something I can use, I can go hunt for more info on the subject or ask an at
least somewhat intelligent question on the list.]

For example, in the User Documentation, there are sections for Generators,
Transformers, etc and then within each of those sections there is a page on
each one (such as a page for File Generator, a page for HTML Generator,
etc). I like this concept.

Selectors: Parameter Selector + Request Selector
But the "Selectors" section just has an overview page, and no pages for each
Selector or examples of how to use them (aside from a few examples, mixed in
with other stuff, of the Browser Selector).  The other selectors are
mentioned *very* briefly at the end.  I was interested in ***Parameter
Selector*** and ***Request Selector***, but could find no docs for them or
examples in the examples/samples code.  I managed to find some info
scattered through other docs, the source code and the mailing lists, but a
doc would have saved me some trouble.  

The doc could include: why & when to use them/what problem could they solve;
how to use them (how to declare the component, sample pipelines, different
options for specifying the parameters)

Readers: (in general) + Resource Reader
Also, there is no "Readers" section at all.  To this newbie, Readers seem
kinda important and their basic use seems pretty straight forward, but
how/when to use them was not immediately obvious to me.   I had no clue
until I asked a dumb question like "Why doesn't my .gif show up in my page?"
and some kind soul on this list told me I needed a pipeline in my sitemap
for *.gif with a reader.  After looking through the list, I can see lots of
questions along this line from newbies, or asking "how to serve static
content?"  Maybe a section on Readers, esp **Resource Reader**, explaining
why/when to use it and some examples of how to use it, would help people
understand and then we wouldn't ask those questions.  

The doc could include: basic overview of what a reader is; the why/when to
use part suggested above; how to use them (component declaration, sample
pipelines, maybe point user to the sample sitemap as it contains a lot of
examples); different mime-types that are available

Readers: Database Reader
**Database Reader** was also of interest to me.  Is this something that
isn't used for some reason?  I could find no docs on it at all, not even
mentioned anywhere other than the API, which by the way, seems to be missing
some essential parameters (like <use-connection>)that seem to be needed for
its operation.  I stumbled across it by accident in the mailing lists which
did contain a nice example (thanks to that person for writing up the
solution to his problem for others to read).

The doc could include: what the reader does/why/when to use it; how to use
it (component declaration; sample pipeline; sample xml/xsl);
limitations/things it can't do

I think I could start to write some basic information on each of these
subjects, but it would not go beyond the basic/newbie stuff, as that is all
I have been able to implement thus far.

Would these documents/this kind of info be useful to have on the site, or is
it just too basic/easy????

If you folks think it could be useful, I'll write a draft document.

Beth Naquin
1145 Broadway Plaza STE 200
Tacoma, WA 98402


View raw message