Re: Docstrings and manuals

[Eli Zaretskii]

> Cc: address@hidden, address@hidden, address@hidden
> From: Dmitry Gutov <address@hidden>
> Date: Sun, 17 Apr 2016 22:59:21 +0300
> 
> > IOW, writing a good manual is still a human activity that cannot be
> > easily automated.  Ideally, doc strings should be phrased like
> > reference material, covering all the traits as tersely as possible,
> > while the manual should provide an easier reading with more continuity
> > text and even some explanations why things are the way they are.  At
> > least IMO.
> 
> That sounds fine, and maybe this way is best for the more complex 
> subjects, but in general I'd prefer to see docstrings also written with 
> readability in mind.

This would make them too long ad wordy, something we'd like to avoid,
I think.