cocoon-users mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "David Leangen" <>
Subject RE: New documentation project?
Date Sat, 13 Nov 2004 08:07:23 GMT

Hi, Upayavira.

First, I want to express my thanks for all your efforts, and those like you.
You have always been very active on this list and have helped me on several
occasions. Thanks!

Second, I want to stress that my post was in NO WAY intended to be negative
towards anybody. I very much respect the efforts of all the individuals who
contribute to the project. I was merely trying to point out some kind of
practical solution. I hope that you or anybody else did not see it as a
negative criticism.

Ok, so with that out of the way, here is the reply to your questions.

> Can you explain more what you mean here? Obviously you feel that
> 'traditional members' are 'blocking' the creation of documentation
> somehow. Can you explain more how you perceive this? I am _very_
> interested to understand..

This is not exactly what I was trying to express. Again, I must stress that
my comments are not intended to be negative. I am just trying to make some
observations in the hope of being helpful. :-)

I think that there are two issues here. The first is that in addition to the
actual hierarchy, there is a kind of de facto hierarchy in the project.
Officially, on the top is the PMC, then the committers, then the users.
Unofficially, there is the project founders, then the very active
contributors, then the not-so-active committers, then the active users, then
the "newbies" and others. I think that there is a kind of natural tendency
to revere the project founders and active committers, so that even if they
do not actively "block" any attempt at a new direction in terms of
documentation, their say in the project has--as a natural course--more
weight. If it weren't this way, the project would be chaotic, so this kind
of natural and subtle hierarchy is necessary. The unfortunate side-effect,
however, is that it can in some cases stiffle new ideas, which is what may
be happening in terms of the documentation.

As one practical example, you'll notice that when a new user makes a post to
the list, he/she inevitably begins with "I'm only a newbie, but..." as if to

As another practical example, let's take a suggestion I made several months
ago, to which somebody (I don't remember who, and it's not important for the
example anyway) replied. Oh, and please do not reply to this example, as it
is only indended to explain what I mean and not to spark any kind of debate
on the content of the example itself.

I suggested that we should think of a new "positioning statement" for the
Cocoon project. Current, we say something to the effect of "Cocoon is a type
of glue for your web applications". This is very true, indeed. The problem,
however, IMNSHO, is that this type of statement is very ineffective for
communicating Cocoon to people who do not know the project. This type of
branding must immediately make the listener understand what the project is
about. The problem with the current statement is that the first reaction of
the reader is... "huh?" My argument was that unfortunately, in most cases,
when people can't connect with the product, when they don't understand, they
will move on and, for instance... use Struts. The committer in question
replied by very simply saying "I think this is fine." No veto and no
blocking: just stating a very valid opinion. In practice, however, unless
the proposer of the new idea is extremely motivated or simply insensitive to
the opinions of the Cocoon veterans, this _does_ block the process.

The more important issue, however, is that the committers are in too deep.
The cannot have the same perception as new users since they are not at all
on the same point of the learning curve. I think that even for the best of
us, it is really difficult to really, truly emphasise with new users when
we're so far ahead. So, despite the best efforts of the active committers, I
think that by nature they are not well suited for the job. They can act as
references and advisors, certainly! However, except for very exceptional
cases, I generally think that they would not make good project leads.

Then, as Derek pointed out, except for rare cases, developers are generally
not great writers. Hey, we're too "smart" for that kind of mundane work. ;-)

> Are you suggesting that you would feel worried about having full commit
> access to Cocoon and would prefer to have it on just documentation? Or
> are you suggesting that you think 'traditional members' would prefer it
> if you had that sort of access?

That is not what I was intending to say, but I will however reply to this,
speaking only for myself, of course.

I would not feel uncomfortable having full commit status because I would use
that status responsibly. I would not, however, feel comfortable actually
committing code. The reason is that the active committers are such strong
developers and are so far ahead on the learning curve that I would feel very
much out of place and perhaps a bit intimidated. I'm wondering if this isn't
so for others as well...

In terms of the documentation, however, I would gladly commit, though my
opinions and views would surely inspire at least a dozen opposing views, as
I'll discuss below.

> I'm very interested in hearing more from your side. I know a lot about
> the 'traditional' way of doing things, and obviously, right now, it
> isn't working, so we need to do something else.

One of the problems is that the community has become too large. This means
that there are too many opposing views. I think that it is no longer
possible to reach any consensus easily. I believe, based on your posts as
well as those of others that there is a willingness to work on
documentation, so that's not the problem. The problem is getting everyone to

So, with all that in mind, this leads me to conclude that the most efficient
approach would be to start afresh, seperately from the main Cocoon project,
with a small core team of dedicated people. Once this new project or
subproject reaches critical mass, it could then be reincorporated into the
main project. By then, there will be enough momentum that the documentation
should continue to head in the right direction.

> So you don't feel up to taking the lead, but do feel up to helping.

Almost. I would love to take up the lead in such a project. However, I have
too many time constraints. I believe that the lead has to have enough
availability to tackle such a large and important project. So, I would
instead gladly contribute to such project within these contraints.


To unsubscribe, e-mail:
For additional commands, e-mail:

View raw message