Re: docstrings and elisp reference

[Richard Stallman]

[[[ To any NSA and FBI agents reading my email: please consider    ]]]
[[[ whether defending the US Constitution against all enemies,     ]]]
[[[ foreign or domestic, requires you to follow Snowden's example. ]]]

  > I was thinking (naively?) that having the docstrings on one side
  > and the reference on the other side was not a very efficient way
  > to maintain documentation. Is everything in the documentation
  > actually written by hand based on the docstrings? Wouldn't it be
  > nicer to have good docstrings and use them directly in the
  > documentation to avoid duplication of work?

Absolutely not!  That's a recipe for a bad manual.  The text of a good
manual section is totally different from a series of doc strings.

Doc strings are read one by one.  Each one describes one function or
variable in isolation.  They are written specifically for this kind of
use.

By contrast, a section in a manual describes several related functions
and variables, and it should be written in an integrated way that
flows smoothly.  Meanwhile, common material should be stated only
once.

-- 
Dr Richard Stallman
President, Free Software Foundation (gnu.org, fsf.org)
Internet Hall-of-Famer (internethalloffame.org)
Skype: No way! See stallman.org/skype.html.