[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: module documentation draft
From: |
Eli Zaretskii |
Subject: |
Re: module documentation draft |
Date: |
Sat, 30 Sep 2017 00:03:17 +0300 |
> From: Philipp Stephani <address@hidden>
> Date: Fri, 29 Sep 2017 20:39:15 +0000
> Cc: address@hidden, address@hidden, address@hidden
>
> 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?