Mailing-List: contact cocoon-users-help@xml.apache.org; run by ezmlm
Precedence: bulk
Reply-To: cocoon-users@xml.apache.org
Message-ID: <3D1CCE25.9050901@apache.org>
Date: Fri, 28 Jun 2002 22:59:17 +0200
From: Nicola Ken Barozzi <nicolaken@apache.org>
Reply-To: nicolaken@apache.org
User-Agent: Mozilla/5.0 (Windows; U; Windows NT 5.0; en-US;
 rv:1.0.0) Gecko/20020530
MIME-Version: 1.0
To: cocoon-users@xml.apache.org
Subject: Re: Giving up! Cocoon too big, slow and confusing
References: <FCEPLAOECPOAGINFDFCHGEBEFJAA.per@onclave.com>
Content-Type: text/plain; charset=us-ascii; format=flowed
Content-Transfer-Encoding: 7bit

First of all, thank you very much for this detailed analysis, it really 
helps :-)

Per Kreipke wrote:
> I sympathize with John's original concerns. We've been using Cocoon
> successfully since version 1.7 and love what it promises.
> 
> However, as everyone has mentioned there are significant hurdles to overcome
> to become productive enough to contribute (as everyone is demanding) and
> some shortcomings that should be rectified.
> 
> Anecdotally: We're in the midst of converting to C2 and it's been a month
> and we're still not done. The reason is simple: you can't jump in and use it
> from just the documentation, you have to look at the code. Imagine how large
> the group of potential users is that can't (or understandably won't) do
> that.
> 
> Here are some concrete suggestions, some of which may irritate. My
> apologies.
> 
> 
> 
> Stop suggesting that the people who are complaining contribute
> =========================
> 
> I don't have a beef with the people exhorting people to contribute, but
> there is a chicken and egg problem of getting to the point where 1) it's
> worth my time to learn it 2) what I contribute is worthwhile to others.
> 
> The gist of the first 10 replies to John's original post was for people like
> him to write the missing docs. He was talking about _starting up_ with the
> project and you're asking him to write documentation already? He barely got
> it running and much less committed to using it. We're really talking about
> getting people committed enough to contribute. They won't do the second
> without the first. And there are 1000's of other open source projects
> looking for contributions as well. Are we supposed to contribute to all of
> them to use them?

No, you are right. But it's the complaint that irritated some.
We are working on this for free, and it seemed just an unfair complaint.
*Seemed*, not that it was, as the author has tried to explain in 
subsequent letters.

> Second, they're in many cases the wrong people to do so. The people who
> write documentation should know something about their subject. Many of us
> complaining about the docs don't know enough about C2 to write a coherent
> FAQ, though not for lack of trying (desperately). I'm dying to contribute
> but I still can't string together a coherent page about how C2 works or even
> what a best practice or pattern is for any part of C2 [my notes are only
> worthwhile to our other developers because they sit next to me and I can
> answer questions quickly in person].

Ok, this is what you could do, that I, as a committer, am really not 
able to do anymore: tell me what you want me to write in specific, tell 
me the title of the page, the paragraphs, what problems you want to see 
solved in the examples.
As good as I can be to write code, I'm really unable to document it as 
you would need me to. That's why I need this kind of help.

> Third, the people who write documentation should be able to write. However,
> while the complainers might not be able to write, as Diana correctly
> suggests, there are other ways to contribute. To the complainers (myself
> included): pick your area of contribution, be it testing, writing, coding,
> email, whatever, and contribute.

Yes, whatever. Just make it concrete :-)

> Fourth, it's the responsibility of the coder to document his contribution.
> As was mentioned in more than one reply (visavis the POI project), there is
> a horrid lack of detailed documentation about the purpose, correct use and
> internal workings of the C2 parts that every newbie is expected to use. E.g.
> the actions, transformers, generators, etc are sketchily detailed; instead,
> we're expected to use the samples to learn. Another example, there are
> components in the code that aren't in the documentation (no, updated
> documentation shouldn't wait for Forrest to be done).

We should refrain maybe from putting in the main branch the scratchpad 
stuff if the documentation team hasen't +1ed the move.
Do you think this could be a good rule?

> Shorten the learning curve
> ===========================
> 
> Every new user of Cocoon follows some kind of growth curve through (choose
> your own labels):
> 
>  newbie (unconvinced)
>  user (convinced)
>  developer (contributing)
>  evangelist (committer)
> 
> If you plotted the upward sloping productivity curve through those stages
> (even _after_ they already know XML), you'd noticed how long and flat the
> newbie and user stages were. I would hazard that the curve for other
> projects mentioned so far in this thread are much shorter.
> 
> The goals of the Apache project explicitly mention users for a good reason:
> without them, Cocoon is an academic exercise. Arguably, it doesn't say whose
> needs are paramount, the contributors or the users. I believe that the needs
> of the contributors come first at the beginning but as the project matures,
> perhaps the users' needs become more important. In the pyramid of people
> using C2, you'd hope that users at the base were the largest group and that
> their needs might be paramount.

Personally, I have a really hard time in understanding how to explain 
Cocoon. I have done it face to face lately, and it's really hard for me, 
because of the complex picture of it I have in mind.

I repeat, now I see the need for the cocoon documentation project, since 
I really understand that I need help to convey my ideas.

> Samples: gear them towards solving real world problems
> ======================================================
> 
> Once you're done with the simple samples, not enough of the samples are
> geared toward solving real architectural problems every web app developer
> has to build. [Aside: don't ask me to contribute any because I still haven't
> been able to get any really useful code to contribute in the month I've been
> using it].

Please just write your problem and explain me what has maked you stop in 
solving it. Maybe this can help me help you.

For example, I've seen that there are problems in installing bare Cocoon 
systems, and starting a new project.
This is why the refactoring of the samples is being done.

> This goes back to the question of why aren't there more plug in libraries
> for Cocoon like there are for many other web frameworks? It's probably not
> because Cocoon Blocks aren't done, it's probably because it's too hard
> learn.

Because Blocks aren't done yet I guess.

> Updates to the online docs
> ==========================
> 
> - don't wait for Forrest to update the online docs. You have users now, they
> need help now. And Forrest is looking like it's slipping into the same sort
> of release schedule as 2.1.

Not really.
Forrest is already running on a test system.
But since we are dealing with Apache stuff and security, we need to 
assure that it all works well.

> - provide online documentation for all of these: the 2.1 HEAD branch, 2.0.2
> release, and 2.0.3 dev branch. The online docs don't seem to say which
> version they refer to. It's incredibly frustrating to look there and find
> them out of date with the version you're using. And requiring people to
> install the product to see the 'current' docs is very annoying.

Good point.

> - add mid-level architecture docs. The Java docs don't give enough detail
> about program flow and who calls what from where.

Mid level? What is mid-level?
You see, I really have a hard time in understanding.

What is low level? What is mid level?
For me Cocoon is just... Cocoon ;-)

> - make the docs searchable (without requiring an install). At least provide
> links to Google and the AIMS group at the top if nothing else. If Google is
> all you add, I suggested on the dev list that perhaps another DNS entry like
> cocoon.xml.apache.org would help hone the search for Cocoon only instead of
> searching across all of XML Apache. I bet this would cut down on the list
> traffic right away.

Yes, it's in Forrest.

> - these mailing lists are great but they make it hard to browse and find
> topical answers. Sure, I can search them on the Aims group but it doesn't
> group them nor does it show an entire thread. Maybe that's what this
> wikiland thing is supposed to be but it's down so I can't tell.

Hmmm... gotta think about this.

> Now that I've had my say, I'd love to implement every one of the suggestions
> above myself for you but haven't the expertise to do so, yet (I _am_ trying,
> very hard). But I hope that this counts as a contribution :-),

Gee, a GREAT one! :-)

I think that now I fully understand why Cocoon needs a Documentation 
Project :-)

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