Re: Trunk still not open

[Eli Zaretskii <eliz@gnu.org>]

> From: Jambunathan K <kjambunathan@gmail.com>
> Cc: Dmitry Gutov <dgutov@yandex.ru>,  emacs-devel@gnu.org
> Date: Sun, 16 Mar 2014 09:27:08 +0530
> 
> 
> To the below list, I would also add this (just for emphasis).  Eli, I am
> not saying it is an oversight on your part.  So don't pounce on me :-)

It's not an oversight, because I didn't intend to provide a checklist
of how to document a feature, only how a description suitable for a
manual _differs_ from a doc string.

>     1. Document the design decisions

Definitely not!  Users are not interested in design decisions, they
are interested in how things should work as designed.  Sometimes,
describing the latter will hint (or more than hint) on the former, but
it's definitely not an end in itself.

>     2. Provide some historical context or add a personal note

Not needed, IMO, and will generally bloat the documentation for no
good reason.

>     3. Consolidate (as in "bring together") various aspects of the
>        feature "scattered" across multiple files or symbols in a single
>        node and provide a cohesive narrative.

Yes, a feature should be generally described in one place, and then
cross-references to that place put in related sections.

> The nodes on overlay, text properties, extents is a good example of (1).

That's the odd one out, and the reason is lost in history that only
old men such as myself remember.