Re: Docstrings and manuals

[Eli Zaretskii <eliz@gnu.org>]

> From: Stefan Monnier <monnier@iro.umontreal.ca>
> Date: Mon, 18 Apr 2016 11:47:17 -0400
> 
> > I think that the two should have a different purpose. I would like more
> > "tutorial" information in the manual (in the sense of "here is a bit of
> > code that does something with the functions we are discussing at this
> > point"), while the docstrings should be the main documentation.
> > For myself, I think, being able to get to the docstring easily (probably
> > with a tooltip) from any occurrence of a function or variable in the
> > manual would be excellent.
> 
> FWIW, I like this idea.  I think we could reduce the amount of
> "reference info" in the manual (a part that's already available in the
> docstrings) by referring to the docstring instead, and instead increase
> the amount of explanation giving tips/examples about how to use it.

Then the manual will be a very awkward reading, even on-line.

To say nothing of the fact that the current doc strings are usually
much worse than the documentation in the manual.

IOW, let's first make sure every changeset is accompanied by good
documentation, and only then consider such significant changes.