cocoon-users mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Upayavira>
Subject Re: New documentation project?
Date Sat, 13 Nov 2004 09:37:36 GMT
David Leangen wrote:

>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.
Rest assured, I never took it that way. I know there's something wrong, 
and I want to understand more what we can do to improve things. 
Understanding others' perspectives can only help.

>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.
You know something - I find this utterly fascinating. You may have 
noticed my name. It is my Buddhist name. I am a member of the Western 
Buddhist Order. This order, and its associated Buddhist movement, 
functions as a meritocracy. There are often frustrations expressed about 
how this movement works, and how it blocks creativity, when its very 
existence is about facilitiating creativity. Now, the funny thing is, if 
I replaced every reference in the above paragraph to Cocoon with a 
reference to this Buddhist movement, it would still make sense.

So, what I deduce from this is that the above concerns are in some way 
inherent in meritocracies, which is exactly what Apache, and thus 
Cocoon, is.

People 'below' in the meritocratic hierarchy feel blocked and stifled by 
those 'higher', when those 'higher' don't perceive themselves as doing 
anything to cause such a block.

In fact, a lot of this has to do with the fact that, in a meritocractic 
society, it takes time for people to learn how that society functions, 
and takes time to become an effective member of that society. It is 
necessary to have some understanding of that society in order to really 
effect change within it. And for those that don't yet have that 
understanding, or don't feel that they do, that can be very frustrating. 
And when those 'higher' try to explain how the society works, it can 
appear as if they are 'blocking'. In fact, they are usually trying to 
draw people in, to explain that which needs to be known before effective 
change can happen. However, it often doesn't come across that way.

The other side of meritocratic society is that people are very often 
volunteers. Those 'lower' come to have expectations of how those 
'higher' should behave (e.g. replying promptly to questions on mailing 
lists, fixing bugs quickly, or giving time to newcomers to a Buddhist 
movement who are having a difficult time...), but those 'higher' are 
often busy, lacking in time, or lacking in emotional or other resources 
to do justice to that which they themselves aspire to do.

A newcomer says, "I want to get involved". Someone involved says, "then 
do this to help me". The newcomer says, "okay, look at this for me", the 
involved person says, "ah, I'd love to, but I don't have time". Bingo. A 

It seems to me that the people who actually manage to get involved with 
Apache are those who manage to get to grips with what a meritocracy is 
and how it works. It is a simple process really:
 * act. Do something constructive. Contribute (wiki, code/doc patches 
for SVN, etc)
 * keep going
 * your positive contribution is noticed
 * at some point, that contribution is recognised, and you are given 
access to the repository.

And I really don't see why this can't happen more, and for people who 
are only interested in documentation (i.e. non-coders).

>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. ;-)
I totally agree. However, as I have heard said elsewhere, "committer" 
refers to "commitment to Cocoon" rather than to "coding" for Cocoon. 
There are one or two active committers who have never, to my knowledge, 
committed anything.

I'd love to see us having a new breed of committer that wants to work 
with the coders (as described so well in Ralph's reply to your message) 
to improve the quality documentation. I will do what I can to make this 
happen. And I am willing to offer some suggestions and practical help in 
getting this to work within the context of the Apache meritocratic system.

>>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...
Okay. That is very useful for me to hear. I would love to hear if others 
feel the same or would prefer not to have commit access to code.

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

>>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
In meritocracy, it is almost always possible to achieve some level of 
concensus. My Order is struggling with this too (having reached 1000 
members, with no formal power hierarchy within it at all).

As Stefano has said, Apache is a meritocracy from the outside, and a 
'do-ocracy' from the inside. A do-ocracy is basically, "Those that do, 

So, if some of us decide to do it, with the backing of some committers, 
I suspect we will quite quickly get wholehearted backing.

Preparedness to act will be noticed.

>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.
That is one approach. My preferred approach is to start small, with 
small incremental changes to what we have currently got. Starting with 
the Wiki, where anyone can participate. If we pull the content on the 
wiki together (see for a good 
place to start), we can start to build a good body of content - cut our 
teeth on something safe. Then, if we want, we can move some or all of 
that content across to the main Subversion repository at a later stage.

>>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.
As is the case with most of us! I hope/plan to help more with this, have 
the enthusiasm and experience of Apache, but perhaps lack in knowledge 
about documentation writing. If you're prepared to help, maybe we can 
come up with something good.

I hope this missive is relevant and not to rambly!

Regards, Upayavira

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

View raw message