cocoon-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Diana Shannon <shan...@apache.org>
Subject Re: docs & misc
Date Thu, 27 Jun 2002 12:19:40 GMT

On Thursday, June 27, 2002, at 02:34  AM, Mikhail Fedotov wrote:

>> After just a few hours of poking around I have decided
>> that it will be much simpler for me to simply hand-code
>> a whole hat-full of servlets than to try and pull any
>> meaning out of Cocoon and it's documentation.
>
> Two things to mention:
>
> 1. I've been talking here about documentation in form of
> dictionary, where is no structure and long docs, just
> complete descriptions of components and their parameters;
> it is the quick way to produce complete components
> documentation that helps in creation of more complex
> documentation. If someone will become interested in
> lowering the difficulty of writiting docs (that I've been
> talking about), and not just writing another docs page
> (that I've been told to do as an response), he could arise
> that topic again.

Well why don't you check out wiki dictionary effort made with Cocoon? 
Perhaps you could help build that dictionary.
   http://www.anyware-tech.com/wikiland/


> 2. About the current docs. They aren't _that_ bad, there is
> much of information. But it looks more like an student
> work, i.e. it gives impression of work made, but not
> optimized for easy understanding and using.

Try not to jump to conclusions about why the state of documentation is 
what it currently is. I made that mistake earlier on this list. ;-) I 
continue to learn new factors almost every day why producing good docs 
is difficult in this context. I could add a hundred items to your list. 
Think of the quality of docs as an indicator of a community's evolution. 
When more people come forward to help improve existing docs, and 
contribute new docs, then they will improve. No sooner and no later. If 
this keeps Cocoon from reaching new audiences, then that's just a 
result -- it isn't necessarily a problem, just a phase of growth. There 
is an effort at Apache Forrest to improve underlying documentation 
architecture. If you don't want to contribute new/revised docs to the 
Cocoon project, perhaps you'd be interested in supporting that project's 
architectural efforts?
   http://xml.apache.org/forrest/

> Here is one
> good model usable in too much contexts to mention, and it
> is also good in writing docs:

I have built a lot of models in my professional life, and I'm not sure I 
would be so brave as to model open source community dynamics ... ;-)

<snip />

> Symptoms - complex webapp, many documents, big hierarchy,
> difficulties with all this; some paragraphs about it.

I don't agree that a complex webapp is a "symptom" of a problem. I think 
the problem that Cocoon is trying to solve is complex. As for "many 
documents," I agree some could be refactored however isn't going to 
happen until Cocoon migrates to a Forrest architecture (in process 
already). At the point, many more options to improve the docs structure 
will become available to us. It just takes time when everyone is a 
volunteer. We are also making the best of available resources, which at 
the present time, includes a static web site.

Still, I prefer more docs. I don't think there are too "many" docs. I 
also want to increase the author pool. With difficult, complex subjects 
like Cocoon, sometimes you need multiple voices to say the same thing, 
just a bit differently. When you are learning something new, and you 
have the luxury of buying books, wouldn't you prefer to buy more than 
one, even if it's about the same topic?

> Causes - hierachy isn't structured, components dependence
> is out-of-control, bad code reuse, too much amount of
> everything, etc; some paragraphs about it.
>
> Outcome - doing things in a more structured way; some
> paragraphs about it.

You can have all the structure in the world but you still need writers. 
IMHO, the hardest part is writing well. If we make writing "easy" by 
removing so-called architectural obstacles, does that mean we'll 
automatically have "good" content? I'm not sure about this. Don't get me 
wrong, I think architectural improvements will help immensely. However, 
you probably are aware that many authors have the additional challenge 
of having to write in a non-native language. Regardless of what you 
think about the docs, I really admire the people who have contributed 
docs so far. And I'm also excited about the books coming out.

> Resources - use of SoC pattern with Cocoon2 as a tool,
> transforming the hierarchy into tree with no dependency
> between branches; some paragraphs about it.

What do you mean by hierarchy? The documentation hierarchy? If you are 
concerned about 2.1 docs being made available with 2.03 docs, then isn't 
it enough to note, in very clear and visual terms, what content applies 
to what branch? The 2.1 docs we have are very good. I think they help 
users understand some of the great stuff that is going on in the HEAD 
branch. As long as they are warned, I don't see the problem.

Diana


---------------------------------------------------------------------
To unsubscribe, e-mail: cocoon-dev-unsubscribe@xml.apache.org
For additional commands, email: cocoon-dev-help@xml.apache.org


Mime
View raw message