cocoon-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Sylvain Wallez <>
Subject Re: [vote] Diana Shannon as Documentation Coordinator
Date Tue, 16 Apr 2002 15:32:24 GMT
Stefano Mazzocchi wrote:

>Ladies and Gentlemen,
>this is a somewhat atypical request for vote so it requires a deeper and
>more detailed explaination.
>Cocoon has reached a point where its technical quality has far exceeded
>its overall 'usability', in the sense of the ability for users to 'use
>the system for their needs'.
>Many are expressing their concerns about the fact that Cocoon is a
>developer framework, and the road to its use is normally so steep that
>very few can manage to get everything out of it.
>The best way to lower the gap is to have better docs. Better means:
> 1) more coherent
> 2) edited by people that knows the english language (since we use
>english as our default natural language) and have editing skills
> 3) maintained regularly
>I've been approached by Diana Shannon who has volunteered to step in and
>help with the process of creating a better documentation. She explained
>to me her intentions, her skills and her 'devotion to the cocoon cause'
>(so to speak :).
>I've challenged her offering a 'documentation coordinator' job overhere.
>Just like we have a 'release coordinator', I think it makes sense to
>have a 'documentation coordinator'.
>The job includes:
> 1) planning and proposing a better (as defined above) documentation

That's definitely needed and definitely critical if we want Cocoon to 
have a larger audience.

>  2) coordinating the authoring effort (means: kicking some asses if
>people commit code without committing docs that go along with them: we
>might go as far as prohibiting code submissions, even in the scratchpad,
>without appropriate documentation along)

That's good also : we often develop some code urged by our own business 
needs, and documentation always comes last...

>  3) providing editing of existing docs (and future docs)
> 4) managing relationships between users and developers

Don't forget Vadim, the Lord of Cocoon-users :)

>I personally think Diana is great for this job becuase:
> 1) she volunteered (in my book, this would be enough since nobody ever
>did in one of my projects after 5 years of more of OSS... but there is

She deserves a +1 just for having volunteered !

>  2) her native language is English, but she has worked in many foreign
>countries and she speaks several languages.

I personally don't like much writing docs, and having to write them in 
english makes me like it even less. I wish I could write something like 
Berin's "Cocoon, The Play", but I can't :-/

>  3) she has a medium understanding of Cocoon as a user. No developer can
>have this job since he/she would loose the user's point of view. I think
>Diana can be a mix between the two points of view and coordinate them so
>that they converge.

True : it's difficult for a developper to write some entry-level docs 
accessible to the beginner.

>All right, at this point I stop and I ask Diana to chime in and present

I couldn't wait and found at 
an intersting bio : what I've seen there makes me confident in Diana's 
ability for this job.

>Ah, one more thing: she asked me if the community needed samples of her
>skills to provide a vote and I admit it's a little strange to ask to
>give commit access to somebody without having to do anything.
>Well, IMO, volunteering for such a critical yet hard job is enough of a
>statement for my vote, so I vote +1 to have Diana 'documentation
>coordinator' and grant commit access to her so that she can update the
>docs directly.
>Of course, we, as a dev community, must make all possible efforts to
>help her in those situations where she requires help.
>At the end, I'm overly pleased by proposing (finally!) a women in the
>Cocoon Development community.
>So, Diana, please, introduce yourself and introduce your plan of action
>(as you did with me privately) so that the rest of the community can

Yes, please. But you already have my +1 !


Sylvain Wallez
 Anyware Technologies                  Apache Cocoon 

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

View raw message