Re: module documentation draft

[Philipp Stephani <p.stephani2@gmail.com>]

[-- Attachment #1: Type: text/plain, Size: 1432 bytes --]

Eli Zaretskii <eliz@gnu.org> schrieb am Fr., 29. Sep. 2017 um 18:46 Uhr:

> > From: Philipp Stephani <p.stephani2@gmail.com>
> > Date: Thu, 28 Sep 2017 20:25:11 +0000
> >
> >  Thanks! I've also finally managed to get my draft online:
> >  https://phst.github.io/emacs-modules
> >  It's more specification-like and hopefully covers most of the behavior
> of the module API.
> >
> > It would be great if we could have comprehensive documentation in the
> ELisp manual in Emacs 26. So it
> > would be great if others (especially the maintainers) could review these
> two documents. Please focus on the
> > content during the first pass, not on stylistic or editorial issues.
>
> 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.


>
> 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.
What exactly would you want to have changed to turn it into "reference
style"?

[-- Attachment #2: Type: text/html, Size: 2138 bytes --]