Re: Changes in revision 114466

[Eli Zaretskii <eliz@gnu.org>]

> Date: Mon, 30 Sep 2013 12:55:47 +0800
> From: Xue Fuqiao <xfq.free@gmail.com>
> Cc: emacs-devel <emacs-devel@gnu.org>
> 
> IMO every user option and every command needs documentation.

First, the original issue that started this thread was about changes
in the ELisp manual, so user options and commands are not really
relevant.

In any case, please keep in mind the downsides of this "document
everything" attitude: it would bloat the Info manuals to humongous
proportions, for reasons that IMO are not good enough.

Here are some numbers obtained by a series of simplistic searches:

 . There are over 5000 commands in Emacs, and over 7500 defcustom's.

 . Out of these, the Emacs User Manual documents about 1400 commands
   and slightly less than 700 user options and variables.

 . Manuals in doc/misc document 2000 more commands and 2000 options.

So even if we assume that there's no duplicates between doc/emacs/ and
doc/misc/ manuals (I didn't check), a suggestion to document
everything would bloat the manual almost twofold.  If you ever saw the
User Manual in printed format, you know that it is already a very fat
book, holding several hundreds of pages.  Making it twice that would
most probably require to split it into two volumes, something that
makes both the book and its production significantly more expensive,
and actually shoots the FSF, who produces the book, in the foot,
because a larger and more expensive book will get sold less, and thus
cut the revenues even more.

The maintenance burden of maintaining twice more docs is also
something we shouldn't discount easily.  The process of updating and
reviewing the manuals before a release, especially a major release, is
already exceedingly long and painful, typically delaying the release
for many weeks.  Do we really want to make it even more painful?

Meanwhile, most of the stuff that is not in the manual has (barring
any bugs) doc strings, which document those commands and options quite
adequately, and are at users' fingertips even more readily than the
Info manual.  What exactly will we say in the manual, besides
reiterating those same doc strings, and why is that a necessity?

The only serious problem with the doc strings is that they lack the
"glue": the kind of overview and background material that we usually
put in the manual when we describe a significant topic.  So what would
probably be a good idea in order to improve the visibility of those
commands and options that are not in the manual is the following
measures:

 . Add a new manual to doc/misc/, which will be separate from the user
   manual.  In that manual, provide short descriptions of every
   package, with index entries that will make it easy to find those
   descriptions even if one doesn't know the package name, and state
   the file(s) in which the package lives.

 . Improve the doc strings so that "apropos-documentation" and other
   apropos commands would find stuff more efficiently.

I think this is a much more practical way of improving the user
documentation without incurring the kind of overhead that will be
required if we decide to "document everything".