Re: Morally equivalent

[Christopher Dimech <dimech@gmx.com>]

> Sent: Monday, October 17, 2022 at 12:53 PM
> From: "Michael Heerdegen" <michael_heerdegen@web.de>
> To: help-gnu-emacs@gnu.org
> Subject: Re: Morally equivalent
>
> Christopher Dimech <dimech@gmx.com> writes:
>
> > Right.  But I would say that the easiest thing is to write better
> > documentation (in source) as you are writing the code.  At least that
> > part should be good.  The source documentation is the biggest strength
> > of this system.
>
> Sounds excellent in theory.  In reality lots of people are not good at
> writing good documentation.  Or don't want to.  Or hate it.
> Although everybody knows that they _should_ do exactly what you
> describe.  The problem is not that they don't know.

That happened many times at work too.  We all had to go look at the code
eventually.  And had various projects where rewriting was faster than
understanding the code.  Have also seen wrappers on wrappers on wrappers
that ultimately re-used old code from 1969.  Absolutely terrible.  This
was at Lawrence Livermore National Laboratory.  Eventually got fed up of
all that and show no respect towards national labs.


> > The documentation is getting longer and longer.
>
> IME the documentation gets longer approx. in the same rate that Emacs
> grows.  And it still does grow.  Selective reading is not prohibited, as
> is selective familiarization with Emacs.  Documentation is also quite
> good, on average, and also partly redundant, so you even have the luxury
> to choose between several paths.  The hard part in mastering Emacs is
> Emacs, not its documentation.  People do it nonetheless because it's
> worth it.  Others don't because it's not worth it for them.
>
> Michael.

The emacs internals are quite hard.  As are the internals of texinfo.
Selective reading is hard because there are lack of tools and techniques
to automate reliably.  Ideally, people would not have to read the Lisp
Manual, but be able to get what they need selectively.