Re: Next release from master

[Eli Zaretskii]

> From: Dmitry Gutov <address@hidden>
> Date: Wed, 10 Feb 2016 06:13:36 +0200
> 
>     IMO it is very reasonable to require documenting the contributed
>     changes. Without that, code reviews and testing are much harder.
> 
> Not if the feature has appropriate docstrings and header commentary.

IME, people who write high-quality doc strings usually also document
the changes in the manual.  So, sadly, going by the doc strings and
the commentary still requires a non-trivial amount of work for many
changes.

> Hopefully, one doesn't have to read the code to translate the docstrings into 
> the manual (AFAICT, Eli tried not to).

This can only be done with user-level documentation, not with stuff in
ELisp manual.  In the latter case, it normally doesn't work.
Especially if the subject matter is something one has little knowledge
about.  E.g., when I worked on cl-generic.el, even reading the code
didn't help enough, because I was not familiar with CLOS before.

> The person who does the documentation also can ask questions.

Yes, but that makes the process much less efficient, even if the
person who wrote the code lives in a close time zone.  A job that
could take several minutes will take hours or days if one must ask
questions to figure things out.  That's what happened with 'pcase',
for example.