Re: docstrings and elisp reference

[Alan Mackenzie]

Hello, Dmitry.

On Sat, Jun 17, 2017 at 15:46:58 +0300, Dmitry Gutov wrote:
> On 6/7/17 8:28 AM, Eli Zaretskii wrote:
> > There is a difference, that's true.  But the fact that reality is
> > different from the ideal doesn't mean we should give up the ideal, at
> > least not lightly.  And we certainly should consider whether the
> > alternative proposal will produce a far worse situation than what we
> > have today.

> Of course a carefully hand-crafted manual is best for the users. But by 
> how much?

> What we have now is the situation where we don't have a lot of manpower, 
> and more people are interested in contributing code (and docstrings, at 
> most) than there are those whole also contribute to the manual. I'm sure 
> you know it all yourself.

Are we really all that short of manpower?  Compared with the Emacs
project in times past?  My impression is that most contributors here do
their best to update the manuals wrt their contributions.

[ .... ]

> Drew said docstrings are mostly for the interactive case. That's wildly 
> inaccurate: as an Elisp programmer, I almost always look at the 
> docstrings and comments, but very rarely at the manuals. Many others do 
> the same.

For what it's worth, I read the Elisp manual frequently.  I value its
style, its content and its readability.  I also attempt to update it and
the Emacs manual each time I make pertinent changes.  It was the quality
of these manuals which lead me greatly to prefer Emacs over XEmacs
around 15 years ago.

-- 
Alan Mackenzie (Nuremberg, Germany).