cocoon-users mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Nicola Ken Barozzi <nicola...@apache.org>
Subject [DOCS] Concrete suggestion
Date Fri, 28 Jun 2002 20:40:57 GMT
Thank you for taking your time to write this, we really appreciate it.
:-)

I'm taging this mail as "[DOCS] Concrete suggestion" so it can be easily 
retrieved.

Thank you.

Liam Morley wrote:
...
>> We need simple examples, simple use cases, all using the terminology
>> that _you users_ look for in the documentation.
>>
>> What would be really of help are *concrete* examples.
>>
>> It's easy to tell us: when you read the Cocoon documentation, you are 
>> looking for something specific... what is it?
>>
> actually, there are a lot of times when I'm looking for documentation to 
> get a general feel for an issue. Often times the concrete examples don't 
> communicate /why/ I would want to use something, or in what context it 
> might be used.  The only Cocoon how-to (other than the five how-to's on 
> how to write code/documentation for Cocoon, or the 3rd party how-tos) I 
> saw was on XMLForm. I've been using Cocoon for a year, and I haven't 
> used XMLForm once. I really have no gauge (other than the mailing list) 
> on who's using what or what actually needs to be documented.
> I also agree that we need to move beyond simply saying "the 
> documentation needs to be improved" and start talking about how to 
> improve it. I thought about what I was looking for from Cocoon and what 
> I saw as lacking on the website, and came up with the following:
> 
>    * Best Practice(s) Tutorials. There are probably multiple different
>      equally good ways of doing a lot of things with Cocoon, I
>      certainly think that a best practice tutorial is necessary.
>    * Currently, the front page of the Dev Guide says "Here will soon
>      appear an overview of the developer perspective."
>    * Users's Section:
>          o Concepts section:
>                + On the overview page, I saw several things that seemed
>                  outdated, including:
>                      # In "Apache Cocoon Configuration", cocoon.xconf
>                        has moved
>                      # In "Apache Cocoon Work Area", the log format has
>                        changed since that was written.
>                      # In "Use with Tomcat", we've had binaries for a
>                        while now; we shouldn't be pushing users towards
>                        CVS unless they're experiencing a problem with
>                        the current packaged binary/source or they want
>                        the bleeding edge.
>                + On the sitemap page, this looks good, but I remember a
>                  thread mentioning the need for a complete DTD to be
>                  outlined; is that it, or are there other things that
>                  need to be added? I found some good documentation at
>                  <http://outerthought.net/sitemap/>, perhaps this could
>                  be integrated or referred to.
>                + I liked the fact that the "Views" page offered a
>                  motivation section; this explains why I should use a
>                  certain component. I think more doc pages should have
>                  a section like this. (I thought views were only used
>                  for debugging? it looks like I'm wrong, and I may be
>                  more inclined to look into views in the future.)
>                + In the "MRUMemoryStore" section, doesn't
>                  "Implementation" belong in a developer's section, not
>                  a user's section? As a user, I don't think I should
>                  know how it's implemented to use it.
>                + I find the "Persistence" doc a bit hard to understand
>                  (parts of it are broken english). I'm also not sure
>                  how it relates to the "Caching" section, or how it
>                  differs. I think this section could use some more
>                  documentation.
>                + I think the StoreJanitor section would benefit greatly
>                  from a "Motivation" paragraph. At least to me, it's
>                  not immediately apparent what it's for.
>                + I think the databases section is great; our project,
>                  however, wrote a transformer that uses JDBC but does
>                  not involve the Cocoon SQLTransformer. I suppose that
>                  option could be added if desired. (The SQLTransformer
>                  part does mention writing a custom transformer, but I
>                  think the option could be added as its own section of
>                  the page.)
>          o Generators: I realize that certain classes like
>            "PhpGenerator" are optional and aren't much of a priority as
>            far as documentation goes, but I think the text "????."
>            could be cleaned up a bit. On the whole, however, the
>            Generator section has been greatly improved since the last
>            time I saw it.
>          o Transformers: This has also greatly improved since the last
>            time I saw it. From looking at the LDAP Transformer,
>            however, it's hard for me to understand how to integrate it
>            into my existing codebase, or whether I'll have to write
>            customized JNDI code. I'd love it if the LDAP transformer
>            page was cleaned up.
>          o Serializers: this section could use an update. Again, the
>            text "????." shouldn't be seen.
>          o The XSP Overview needs updating.
>    * FAQ's:
>          o The entry "How do I integrate Apache Server and Cocoon?"
>            needs updating, as there are several connectors being used.
>            When Tomcat 4.1.3 is no longer beta, then Coyote will be the
>            default connector, which will introduce JK2; this is bound
>            to confuse a lot of people unless the documentation is updated.
>          o The entry "How do I hide "cocoon" in the URL's once I
>            integrate using mod_jk as shown above?" could be improved,
>            as I did not find it helpful. I could make specific
>            suggestions, but I think that would be outside the context
>            of this list.
>          o I think an entry "When should I use CVS?" should be added to
>            the CVS FAQ section. Not all users need it, and not
>            everybody knows if they should use it or not.
>          o I think an entry concerning the sitemap should be made in
>            the "Configuring Cocoon" section on sitemap configuration
>            that gives a *brief* overview and points towards other
>            sitemap docs. Although we have great sitemap documentation
>            elsewhere on the website, people will still come to the FAQ
>            looking for it.
>          o I tried the debugging FAQ and got an exception (although I
>            can post that as a seperate email).
>          o In the Aggregators section, I would benefit from an entry
>            entitled "Why would I use an aggregator?" discussing some
>            common examples of aggregator usage.
> I apologize for the length and realize that this subject may be better 
> served if it moves off the users list, but I wanted to put some of this 
> on the table and put my money where my mouth is.
> 
> Liam Morley
> 


-- 
Nicola Ken Barozzi                   nicolaken@apache.org
             - verba volant, scripta manent -
    (discussions get forgotten, just code remains)
---------------------------------------------------------------------


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


Mime
View raw message