Re: Next release from master

[Eli Zaretskii]

> From: Alexis <address@hidden>
> Date: Wed, 10 Feb 2016 14:28:18 +1100
> Cc: address@hidden
> 
> i would also like to suggest that part of the "it works" phase should involve 
> writing (or at least attempting to write) proper documentation for the 
> feature(s) involved. Yes, the "works right" phase might well involve 
> modifying some of that documentation, but proper documentation is important 
> to help people understand how the feature is intended to work and/or be used.

I think we should indeed move towards requesting that each change in
behavior is accompanied by a suitable change in the documentation.
Other projects (GDB is one example) have such a policy, and it works
well enough, even when the person who submits a patch has difficulty
expressing themselves in English (they are helped to overcome that
difficulty).

> Further, it seems to me that Eli is ending up having to write a lot of 
> documentation of other people's code, which i feel is unfair on him.

Forget about me: it's unfair to all of us.  It took me 2 months to
catch up on all the stuff that should have been documented, which had
to be done before the first pretest could be put out the door.  Two
months of working almost entirely alone on nothing but updates to the
2 main manuals, using up all the time I could afford, doing almost
nothing else for Emacs.  That's 2 months of delay in releasing Emacs.
Do we really want to pay that price each time we are about to make
another release?

> If GNU Emacs being "self-documenting" is a headline feature, then 
> documentation should be an integral part of code development, not Somebody 
> Else's Problem, where "Somebody" is Eli.

Don't count on me being in that role for too long ;-)

Thanks for raising this issue.