Re: Community improvements to the Emacs Widget Library manual?

[Eli Zaretskii]

> From: Bryce <bovine@cyberscientist.ca>
> Cc: maurooaranda@gmail.com, emacs-devel@gnu.org
> Date: Mon, 10 Jul 2023 18:52:59 -0600
> 
> > If you want to add tutorial-style sections, that could also be a good
> > idea, provided that the subject is so complex that reading the main
> > description is too hard without first reading a tutorial introduction.
> 
> Should any tutorial content, inserted or appended to the manual, only
> cover content that would likewise be too complex to understand? Would
> example content be more appropriate in cases where the manual may not be
> clear in some reader's opinions? Would further tutorial content (like
> the example in §2 and §3) be rejected for being too simple or
> "long-winded"?

I don't know the answers, and probably won't know until I see a
proposal for adding such a tutorial.  The devil is in the details!

> Diataxis is something I recently learned of, and I figured it would
> be a good application to the various objectives I was considering
> (What's the syntax of Z widget type? How do I…? Why X? What is Y?).

A good manual should answer all those questions, yes.

> > But the general idea of the existing manual, which is to describe both
> > the user-facing UI and the Lisp-level reference, is correct, IMO.
> 
> Are you referring to something other than the Customize interface in
> this sentence?

I refer to the fact that the manual has a chapter names "User
Interface", which describes how widgets look and are used, and it also
has chapters that describe how to program widgets.

> I'm new to mailing lists, and I'm trying to participate as best I can.
> Let me know if some parts of my reply would've been better–formatted in
> another way or if I'm not as courteous as I could be.

I see absolutely no problems with your responses.