Subject: bug#65913: with-help-window arranges for 'inhibit-read-only' to be set to 't'

From: Drew Adams <[email-masked]>
Date: Thu, 14 Sep 2023 16:03:56 +0000

> In general, there's no need to mention in each and every doc string
> that to learn about some subject you should read the manual where that
> subject is described.  This is trivial, and having to repeat that
> everywhere will just bloat Emacs for no good reason.

Amen.

This is a common request from users, who sometimes
expect a complete answer to their question - aimed
at their particular immediate context/problem - or
a complete understanding of something, to be right
in front of them, at the first page or help msg
they encounter.  And they want it to be aimed at
their particular level of background understanding.

It's an individualistic, "Gimme, gimme, gimme, me!"
approach, naively ignoring the fact that whatever
help they hope to find will likely aim to also help
others, with different backgrounds, questions,
contexts, problems.

I'm guessing this can also come partly from a
frustration from _searching_ as the main - or even
the only - navigation users employ.  Search can be
very good, or very bad.  Some experience/knowledge
are needed to search effectively, as well as good
search tools.

Emacs has good search tools.  The first thing users
should learn is how to Ask Emacs.  The help commands
of course, and later even how to ask using Lisp etc.

A just-what-I-need-right-here-right-now expectation
is a problem for help/documentation in general, but
especially so nowadays, when it's no longer the case
(if it ever was) that readers start at the start of
a book and read sequentially.

Now, more than ever, "Every Page Is Page One".

https://everypageispageone.com/

Readers arrive at a URL by googling or following a
link from somewhere.  Off the web, inside Emacs,
they arrive at an Info node or a *Help* description
directly.

The solution to the "problem" is for every "page"
to provide relevant links to other pages/topics.
Every one.  That way, wherever you start you can
pretty much follow the paths you want, to get the
info you need.

It's not a simple problem with a trivial solution.
Deciding what goes into a given "page"/topic, and
which other topics to link to, is a judgment call
- or more correctly lots of judgment calls.  And
that means that even with the "best" design, for
some set of targeted readers/users, some will be
frustrated.  (Even deciding what the targeted set
of readers should be is non-trivial and involves
compromises.)

A good model of a generally helpful doc system is
Wikipedia.

Emacs help and doc are pretty darn good.  This is
largely because Emacs maintainers - first RMS and
now Eli, in particular - have long been hugely
interested in the help/doc - self-documenting -
feature/aspect of Emacs.  Emacs didn't exactly
invent self-documenting, perhaps, but it nearly
did so.

> Consulting the documentation is one of the
> first lessons that each Emacs user learns,
> and resisting that lesson is not recommended.

Agreed.  There's no excuse for not dipping into
the manuals.  Or for not taking advantage of
other sources: tutorials, videos Q&A venues, etc.
Different users learn differently, of course.

That said, more links from *Help* to manuals
could help, I think.