RE: Ideas/suggestions for docs + offer 2 help (kinda long)

["Naquin, Beth" <Be...@morpho.com>]

Put me down for a document on Parametor Selector, for a start.

-----Original Message-----
From: Diana Shannon [mailto:shannon@apache.org]
Sent: Friday, June 28, 2002 3:50 PM
To: cocoon-users@xml.apache.org
Subject: Re: Ideas/suggestions for docs + offer 2 help (kinda long)



On Friday, June 28, 2002, at 06:30  PM, Naquin, Beth wrote:

> 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)

This would be great.
>
> 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

Again, great.
>
> Readers: Database Reader
> ----------------------------------------
> **Database Reader** was also of interest to me.  Is this something that 
> isn't used for some reason? 

Can someone else clarify the status of this component for Beth?

> 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.

Yes. These docs would be useful -- however basic at first. Some advice 
on how to do it.

1. Check existing docs for existing, even fragmented content. Clearly 
you have already done this.
2. Check java source code for more info or comments. Many times you will 
find explanations there.
3. Write what you can. When you get stuck, posts questions to 
cocoon-users and cocoon-dev.
4. If you don't get enough info, find the names of the people who 
wrote/patched the component. (They are in the source code along with 
their email addresses.) Email them directly about your questions.
5. If you still have holes (and you probably will), leave detailed fixme 
comments in the docs for others to address.
6. Validate you docs.
7. Prepare a patch. See How-To if necessary.
8. Submit to Bugzilla. See How-To if necessary.
9. Email me for any other questions.

If you agree, I'll add your name to a docs-in-process list so no one 
else duplicates your effort.

Big thanks Beth. Welcome aboard!

Diana


---------------------------------------------------------------------
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:     <co...@xml.apache.org>
For additional commands, e-mail:   <co...@xml.apache.org>