Re: Next release from master

[Alexis]

Dmitry Gutov <address@hidden> writes:

> I'm sure Eli (and the rest of us) would be very happy to see you 
> help with documentation.

i'm sorry Dmitry, but i don't agree with the notion that people 
who don't understand the code they're documenting should be the 
first ones to document it. :-P (Though of course, they can 
certainly help clarify things they feel aren't clear in /existing 
documentation.) i don't expect others to document the code of the 
packages i've written, because:

(a) others won't necessarily know what i /intended/ by the code, 
they can only work from what the code /seems/ to do. That makes it 
more difficult for non-me documenters to guess whether something 
is a bug or "working as intended".

(b) i don't assume that my time is much more valuable than other 
people's. i don't think it's a net gain for the Emacs community to 
have somebody else spending, say, an hour or two coming to grips 
with code for the purposes of documenting what they /think/ is 
going on, rather than me spending 5-10 minutes just writing the 
documentation in the first place.

(c) at a basic level, my point was not "i have a problem with Eli 
being the main person writing documentation" so much as "i have a 
problem with the fact that it's /necessary/ for Eli, /or anyone 
else/, to be having to write documentation for code they haven't 
written, because the developers of the code in question have 
treated documentation as Somebody Else's Problem". If you think 
that it's not important to provide documentation for the code you 
write, then okay, but that's not a position i share.

Having said all that, i'd be interested to hear John's thoughts on 
this matter (who i've cc'd), and will follow his lead on this.


Alexis.