cocoon-users mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Ralph Goers <Ralph.Go...@dslextreme.com>
Subject Re: New documentation project?
Date Sat, 13 Nov 2004 08:49:30 GMT
David Leangen wrote:

>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 can't speak for everybody, but just for myself.  I don't like writing 
documents. I write well, but I do tend to go into things too deeply.  
I've noticed that since English is not the native language for many of 
my fellow committers that some of the documentation suffers from that.

>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.
>
My past experience has been that the best documentation comes from 
people who like to write and are technical enough that they can read 
small pieces of code and understand it.  Basically, when I have worked 
with technical writers they ask for an "information dump" where the 
developer sends documentation in a very raw form. The writer then takes 
this information and formulates it into something that makes sense. This 
is a very iterative process as the writer frequently has to go back to 
the developer to get information.

It would be great if we had folks who wanted and were able to contribute 
to Cocoon in this capacity.  I'd certainly be in favor of giving tech 
writers commit access to the subversion repository for the web site, if 
that is possible.  Frankly, the benefits to being a tech writer would be 
huge, IMO.  They would gain a deep understanding of Cocoon and could 
possibly use that to their benefit in teaching others.

>>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.
>  
>
Well, if it stays within Apache that wouldn't be a problem since the 
"lead" is the consensus of the team.


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


Mime
View raw message