Re: module documentation draft

[Eli Zaretskii <eliz@gnu.org>]

> From: Philipp Stephani <p.stephani2@gmail.com>
> Date: Fri, 29 Sep 2017 20:39:15 +0000
> Cc: aurelien.aptel@gmail.com, phst@google.com, emacs-devel@gnu.org
> 
>  I already read this, when this was first announced in April.
>  Unfortunately, the style and the methodology of the description
>  differs significantly from what we use in the ELisp manual. So this
>  text will have to be reworked, and I didn't yet find time to do it.
> 
> As said, I'd like to get feedback about the *content*. Changing the *style* is easier and requires less
> discussion.

I said "style and methodology", and we seem to disagree about what is
and isn't "style".  My "style" is part of your "content".

>  The
>  first step is to convert the tutorial-like description to the
>  reference-style description we use in the manual. 
> 
> I'm a bit surprised that you call my style "tutorial-like". I think it's not a tutorial at all; there's e.g. no end-to-end
> example to step-by-step instructions.

I already said I won't argue about the "tutorial" part, so let's drop
it.

> What exactly would you want to have changed to turn it into "reference style"? 

It's hard to explain without doing the actual work.  For starters, it
is too formal: begins by introducing all the terms, even if that's far
from where they are actually needed in the description; talks about
requirements before describing the interesting stuff; etc.  Then the
order of the sections doesn't always make sense to me: for example,
"Compatibility" should be somewhere near the end.  And there are other
issues.

Doesn't reading a typical chapter in the ELisp manual, such as "Hash
Tables" or "Processes", make the differences clear?

Or let me turn the table and ask you: do you think that text is fit
for putting it as-is into the ELisp manual?