Re: Trunk still not open

[Eli Zaretskii]

> From: Dmitry Gutov <address@hidden>
> Date: Sat, 15 Mar 2014 05:22:52 +0200
> Cc: address@hidden
> 
> Having just now updated the manual WRT to the new
> `blink-matching-paren', I feel quite disgusted by having to document the
> changes in triplicate.
> 
> The docstrings in the code, lispref/display.texi and emacs/programs.texi
> all contain the descriptions of the relevant symbols, each using quite
> different text.
> 
> Writing docs does not come easy to me in general, and editing three
> seemingly arbitrarily different descriptions of the same things is a
> good recipe for a headache. I have no idea how to judge the changes I
> made.

The doc strings and the manuals take different views on the same
features.  The doc strings document only the symbol they pertain to,
with minimal links to others.  By contrast, the manuals should always
describe the features in the context of a larger theme that is the
subject of the containing section of the manual.  This means, in
particular, that the manual text should:

  . contrast each feature with other features and discuss its
    advantages and disadvantages, as in "unlike FOO, this function..."

  . include cross-references to related material and places where
    terminology you use is defined and described

  . provide examples where necessary to clarify the usage of a
    feature, especially when its formal description might not be clear
    enough

  . in general be less concise and more explanatory, since the size of
    the text is less important than in a doc string (it doesn't affect
    the memory footprint of the Emacs process)

  . for the ELisp manual, provide the information that Lisp
    programmers need to use the feature best, such as considerations
    when to use and when not to use it

It is quite rare to have a feature whose documentation in the manual
is simply a repetition of its doc string.