Discoverability (was: Changes for 28)

Discoverability (was: Changes for 28)

[Tom Gillespie]

Hi all,
    There have been a bunch of great discussions in the Changes for
emacs 28 thread. Per request I am responding with proposals in a
separate thread. I have three concrete proposals distilled from the
original thread, followed by a summary of what I see as a common goal
that everyone could work toward -- discoverability. Best!
Tom


Three proposals related to making Emacs functionality more discoverable.
1. Add the Describe sub-menu to the top in addition to having it as a
   sub-menu in Help.
2. Have a set minimal configs, created by community experts, that
   show off the configuration space of Emacs, including configurations
   that would be familiar to users of other popular tools.
3. Maintain the celebration of the diversity of Emacs use cases in
   a separate, but easily accessible repository. This could include
   things like the starter kits. This point is primarily inspired by
   the fact that the default core of Emacs by itself cannot be all
   things to all people, but that doesn't mean that we can't display
   the fact that when configured accordingly, it can be all things to
   all people.


I want to bring up what I see as the fundamental challenge
that everyone in that thread seems to be trying to address, or perhaps
the common goal we are all trying to work toward.  Namely the goal of
discoverability. This is not a challenge unique to Emacs, the whole
world is facing it, flooded with mountains of data, Emacs happens to
be ahead of the curve since it has more features than any other single
piece of software that I know of.

To give an example of the extent of the challenge, I have been
thinking in this area for quite awhile, and yet had no idea that CUA
mode existed under that name until reading the original thread! Maybe
I had spotted it in passing, but I had no idea what it meant. Maybe I
didn't look hard enough. I knew that someone must have created
something along those lines, it is an obvious thing to do, but I never
managed to spot it in the options menu.

I had a similar experience with the Describe sub-menu. When I'm
exploring a new mode I regularly explore the menu to see what
functionality is present. I also learned C-h k, C-h m, and friends and
used them for years. Thus imagine my consternation when I discovered
that there was a whole sub-menu dedicated to making Emacs'
functionality more discoverable but it was hidden down in the Help
menu buried there along with the Emacs Psychotherapist! I pulled
Describe out and made it a top level menu item. Adding Describe to the
top level menu is the kind of thing that could help with
discoverability. It is the tool to discover what is hidden, but at the
moment it itself is hidden!

Since Emacs is for all intents and purposes an operating system in the
same sense that the Linux kernel is an operating system, it has to
follow the golden rules for operating systems which is "never break
user space."  That means that certain seemingly simple and quick
solutions, like changing defaults, are forever off the table. As
others have pointed out, such solutions only seem simple when you
don't account for the tens if not hundreds of thousands of man hours
of needless changes they induce across the user and developer base.

Yet, there is still the challenge of discoverability. I have been
dealing with this in the even more mundane context of trying to
simplify the process of installing Emacs for semi-technical users so
that they can interact with an Org file. This has proved to be a
non-trivial task. There are countless stumbling blocks along the way,
and the power and configurability of Emacs, along with the variety of
starter kits does not help here, it only bewilders. The paradox of
choice at its finest. I have learned the hard way that whatever
benefits you expect from having a semi-technical user running Emacs
with a particular configuration, the cost of getting them there is
still staggeringly high if you don't have the luxury of teaching them
yourself. Simplifying the on-ramp without compromising those users'
freedoms is a technical challenge, especially when they are already
working in non-free conditions.

As others have mentioned, the starter kits help for technical users
and are valuable community assets that are separated from the core for
sound technical and design reasons -- Emacs supports a unimaginable
diversity of use cases when acting as a platform on top of which
others build. From my perspective, the primary technical objective for
core Emacs development has been and should continue to be to maintain
and improve that platform with the same dedication to compatibility
that it has had since its inception. Empowering users is the core
mission and Emacs is the primary instrument. Trying to enshrine a
subset of the use cases for the platform in the core of Emacs itself
thus should probably be considered to be a bad engineering decision
(dangerously close to the "all it's missing is a decent text editor"
joke). Could a GNU sanctioned and managed celebration of the diversity
of Emacs use cases live in another repository? Probably. Linking to
such a resource from C-h C-a would be a revolutionary undertaking, but
perhaps worth the attempt. Regardless, I would caution against getting
pulled into bad engineering decisions by conflating Emacs the git
repository with Emacs the brand.

One possible way to address discoverability that I see (among many
others already discussed, including elements of this one) would be to
have a variety of zero-config options that users can try out at the
click of a button. As suggested by others, there are seasoned elisp
wranglers out there who could create a set of minimal configs that
show off the configuration space and make its diversity visible to
users. Categorize the configs and market them (yes, the dreaded word)
as being familiar for users coming from a certain background.
Presenting these configs and making them discoverable in a way that is
consistent with the values of the project and with respect to the
sacred space that is C-h C-a is a challenge, but one that I think
could be overcome. Given the nature of discoverability, I think that
there will ultimately be a variety of approaches that all work
together to make the enormous variety of features and workflows that
Emacs has to offer more discoverable. The diversity of the use cases
and the diversity of the backgrounds of the users makes it almost
inevitable.

Re: Discoverability (was: Changes for 28)

[Stefan Kangas]

Hi Tom,

Tom Gillespie <tgbugs@gmail.com> writes:

> Since Emacs is for all intents and purposes an operating system in the
> same sense that the Linux kernel is an operating system, it has to
> follow the golden rules for operating systems which is "never break
> user space."

I find the analogy to be fundamentally broken.  We jest that Emacs is an
operating system, but really it is not.  It's a text editor.

I don't see how the "don't break userspace" maxim of Linux kernel
development could be applied to Emacs in any meaningful way.  We deal in
Lisp, not ABI:s.

>               That means that certain seemingly simple and quick
> solutions, like changing defaults, are forever off the table.

If so, it's a new rule.  AFAICT, defaults both can and do change.
See NEWS for Emacs 27.1.

Best regards,
Stefan Kangas

Re: Discoverability (was: Changes for 28)

[Tom Gillespie]

Hi Stefan,
   Thank you for the opportunity to clarify some of my points. Best,
Tom

I will add that I am heartened by other ongoing discussions that indicate
a desire to figure out how to make it possible to

On Tue, Sep 8, 2020 at 7:52 PM Stefan Kangas <stefankangas@gmail.com> wrote:
> I find the analogy to be fundamentally broken.  We jest that Emacs is an
> operating system, but really it is not.  It's a text editor.

I do not think that it is a jest. Further, I think that to treat it as
such fundamentally
undermines real responsibility that Emacs has as a piece of core infrastructure.
It may be a just a text editor to you, but to others it is a language runtime no
different than the JVM, and to yet others it is the heart of their livelihood.

Emacs is as far from notepad.exe (or ed if you prefer the default editor)
as a nuclear missile submarine is from a hollowed out log. Yes, both are
technically seacraft, but a hollowed out log filled with any number of angry
pointy stick weidling men is unlikely to be able to lay waste multiple cities
in a matter of minutes.

> I don't see how the "don't break userspace" maxim of Linux kernel
> development could be applied to Emacs in any meaningful way.  We deal in
> Lisp, not ABI:s.

The example was not intended to be about the superficial implementation
details of the particular technology. It has to do with the responsibility that
a project has toward its downstream users. Projects that treat their user's
time with contempt wither and die unless they have a government mandated
monopoly or the like. Emac's has slightly more leeway than the kernel, but
if we want Emacs to be infrastructure then we have to treat it as such.
Every second that a user has to spend fixing something that broke because
of a change in Emacs has to be weighed against the potential benefit. Those
seconds are no different from the seconds that some userspace developer
(almost never) has to spend fixing something that was broken by the kernel.
Furthermore, the risk for us as developers is that we are isolated from the
realities faced by other users and are massively biased toward decisions
that benefit us and make our work easier. Therefore it seems like a good
idea to approach any changes to default behavior with great care since
it is especially difficult for a project like this to do the user studies or
collect the telemetry required to ensure that those changes don't break
countless workflows.

> >               That means that certain seemingly simple and quick
> > solutions, like changing defaults, are forever off the table.

Please excuse my hyperbole, and allow me to amend that statement
to include "If we entertain the possibility that this means that ...".

> If so, it's a new rule.  AFAICT, defaults both can and do change.
> See NEWS for Emacs 27.1.

As a sufferer under some of those changes, I am well aware of the
pain that such divergences cause the users. I acknowledge that
sometimes those changes need to be made for sake of consistency
with larger refactorings. However, the fact that they do happen should
be viewed as a failure of engineering and not an excuse for future failures.

Re: Discoverability (was: Changes for 28)

[tomas]

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

On Tue, Sep 08, 2020 at 07:51:59PM -0700, Stefan Kangas wrote:

[...]

> I don't see how the "don't break userspace" maxim of Linux kernel
> development could be applied to Emacs in any meaningful way.

But it is: Changes to core are done with consideration towards
users "out there", there is a deprecation mechanism, etc.

"Don't break users" is, I think, common to both. The colours may
vary :)

> We deal in Lisp, not ABI:s.

An interface is an interface is an interface :)

Sure, Lisp gives the user side more leverage than an ABI, which
is in resonance with the GNU philosophy.

Cheers
 - t

[-- Attachment #2: Digital signature --]
[-- Type: application/pgp-signature, Size: 198 bytes --]

Re: Discoverability (was: Changes for 28)

[Richard Stallman]

[[[ To any NSA and FBI agents reading my email: please consider    ]]]
[[[ whether defending the US Constitution against all enemies,     ]]]
[[[ foreign or domestic, requires you to follow Snowden's example. ]]]

  > Since Emacs is for all intents and purposes an operating system in the
  > same sense that the Linux kernel is an operating system,

Emacs is not an operating system, and Linux (the kernel) is also not an
operating system.  Each of them is just part of an operating system.
You could say that both _fail_ to be an operating system in the same
sense.

See https://gnu.org/gnu/linux-and-gnu.html and
https://gnu.org/gnu/gnu-linux-faq.html, plus the history in
https://gnu.org/gnu/the-gnu-project.html.

If there is a sense in which Emacs IS an operating system, I don't
know what it is.  If there is a sense in which Linux IS an operating
system, I don't know what it is.

Ultimately, we can't determine whether the statement is valid.


-- 
Dr Richard Stallman
Chief GNUisance of the GNU Project (https://gnu.org)
Founder, Free Software Foundation (https://fsf.org)
Internet Hall-of-Famer (https://internethalloffame.org)

Re: Discoverability (was: Changes for 28)

[Richard Stallman]

[[[ To any NSA and FBI agents reading my email: please consider    ]]]
[[[ whether defending the US Constitution against all enemies,     ]]]
[[[ foreign or domestic, requires you to follow Snowden's example. ]]]

  > I have three concrete proposals distilled from the
  > original thread, followed by a summary of what I see as a common goal
  > that everyone could work toward -- discoverability. Best!
  > Tom


  > Three proposals related to making Emacs functionality more discoverable.
  > 1. Add the Describe sub-menu to the top in addition to having it as a
  >    sub-menu in Help.
  > 2. Have a set minimal configs, created by community experts, that
  >    show off the configuration space of Emacs, including configurations
  >    that would be familiar to users of other popular tools.
  > 3. Maintain the celebration of the diversity of Emacs use cases in
  >    a separate, but easily accessible repository. This could include
  >    things like the starter kits. This point is primarily inspired by
  >    the fact that the default core of Emacs by itself cannot be all
  >    things to all people, but that doesn't mean that we can't display
  >    the fact that when configured accordingly, it can be all things to
  >    all people.

These are very good ideas.  1 and 2 are quite concrete -- I think
people could go off right now and implement them, figuring out the
details along the way.

3 is not quite as concrete, not yet.  But people could propose sorts of
of configurations we might have starter kits for, and that way we could
make it more concrete.

-- 
Dr Richard Stallman
Chief GNUisance of the GNU Project (https://gnu.org)
Founder, Free Software Foundation (https://fsf.org)
Internet Hall-of-Famer (https://internethalloffame.org)

RE: Discoverability (was: Changes for 28)

[Drew Adams]

>> 1. Add the Describe sub-menu to the top in addition to having it as a
>>    sub-menu in Help.
> 
> These are very good ideas.  1 and 2 are quite concrete -- I think
> people could go off right now and implement them, figuring out the
> details along the way.

Why is #1 a good idea?  IIUC, the suggestion is
to create a separate menu-bar menu for Describe.

To me, Help > Describe makes a lot of sense.
It's not single-click, but it's main purpose is
discoverability - in particular, discovering
keys that describe things.

Menu-bar space is a scarce resource, especially
when mode-specific menus are added.

If we were really eager to sacrifice menu-bar
space by adding more menus there, especially
ones that would be shown in all modes, I can
imagine more important ones to add (Search,
for example, which can include Replace and more
items).

(And other Edit submenus, such as Go To and
Bookmarks could reasonably be moved to File;
they're not particularly about editing.)

Re: Discoverability (was: Changes for 28)

[Eli Zaretskii]

> Date: Thu, 10 Sep 2020 09:53:11 -0700 (PDT)
> From: Drew Adams <drew.adams@oracle.com>
> Cc: emacs-devel@gnu.org
> 
> (And other Edit submenus, such as Go To and
> Bookmarks could reasonably be moved to File;
> they're not particularly about editing.)

They are in Edit because other applications put them (or similar
stuff) under Edit.

The Emacs menu items and their arrangement are not random, they were
well thought of and discussed at length.  There's usually a good
reason behind every choice there.

RE: Discoverability (was: Changes for 28)

[Drew Adams]

> > (And other Edit submenus, such as Go To and
> > Bookmarks could reasonably be moved to File;
> > they're not particularly about editing.)
> 
> They are in Edit because other applications put them (or similar
> stuff) under Edit.
> 
> The Emacs menu items and their arrangement are not random, they were
> well thought of and discussed at length.  There's usually a good
> reason behind every choice there.

I didn't assume randomness.  And there are countervailing
good reasons to move them from Edit (e.g. to File).

Most things in Emacs UI have been "well thought out and
discussed at length".  There's still room for improvement.

Re: Discoverability (was: Changes for 28)

[Eli Zaretskii]

> Date: Thu, 10 Sep 2020 11:30:46 -0700 (PDT)
> From: Drew Adams <drew.adams@oracle.com>
> Cc: rms@gnu.org, tgbugs@gmail.com, emacs-devel@gnu.org
> 
> there are countervailing good reasons to move them from Edit
> (e.g. to File).

Where did you see a Go To item under File?  It makes no sense.

RE: Discoverability (was: Changes for 28)

[Drew Adams]

> > there are countervailing good reasons to move them
> > from Edit (e.g. to File).
> 
> Where did you see a Go To item under File?  It makes no sense.

I don't know that I saw it anywhere.

It makes more sense to me than putting it under
`Edit'.  Likewise `Bookmarks', which is also
(typically) about moving somewhere.

Just as `File' often has entries for accessing
recently opened files, so I see it as having
entries for accessing other "locations".

But I'm not going to argue with you.  It was a
parenthetical remark, which you've jumped on
defensively with comments about `Edit' not being
random etc.  You're well aware that I'm aware of
the deliberation that's gone into menu choices.

I suggest that it would help to move search to
a top-level menu (`Search' or `Find').  And I
suggest that the "go-somewhere" stuff on `Edit'
be moved elsewhere (`File' is an OK choice, IMO).

Just a suggestion.

I don't think `Edit' should be a catch basin.
But yes, neither should `File' or `Tools' or ...
___

FWIW, I've had it this way in `menu-bar+.el' since
1995.  I have other changes there as well, some of
which fit some of what Xah Lee says.

One feature that I think is particularly helpful is
that the local (current-mode) menus are separated
from the others (common menus).  The local menus
come first, followed by a separator and then the
common menus.

https://www.emacswiki.org/emacs/download/menu-bar%2b.el

Re: Discoverability (was: Changes for 28)

[Eli Zaretskii]

> Date: Thu, 10 Sep 2020 12:05:17 -0700 (PDT)
> From: Drew Adams <drew.adams@oracle.com>
> Cc: rms@gnu.org, tgbugs@gmail.com, emacs-devel@gnu.org
> 
> > > there are countervailing good reasons to move them
> > > from Edit (e.g. to File).
> > 
> > Where did you see a Go To item under File?  It makes no sense.
> 
> I don't know that I saw it anywhere.

You never started MS Word?

> Just as `File' often has entries for accessing
> recently opened files, so I see it as having
> entries for accessing other "locations".

File is already a very large menu, apart of being unrelated to moving
in a document.

> But I'm not going to argue with you.  It was a
> parenthetical remark, which you've jumped on
> defensively with comments about `Edit' not being
> random etc.  You're well aware that I'm aware of
> the deliberation that's gone into menu choices.

Others are reading, but.

RE: Discoverability (was: Changes for 28)

[Drew Adams]

> > > > there are countervailing good reasons to move them
> > > > from Edit (e.g. to File).
> > >
> > > Where did you see a Go To item under File?  It makes no sense.
> >
> > I don't know that I saw it anywhere.
> 
> You never started MS Word?

You asked me where I've seen it _under File_.
I replied that I don't know whether I've seen
that anywhere.  I certainly don't remember
where I might have seen that.  Is it important?

Now you're apparently asking whether I've ever
seen `Go To' _at all_, or rather whether I've
seen it in MS Word.  I don't remember whether
I've seen it in MS Word either.

I happen to have Word open now, and I don't
_notice_ it anywhere.  But then again, I don't
see any menus.  What looks like menu-bar labels
(`View' etc.) just seem to change the band of
icons and panels underneath that bar; they don't
seem to show menus.

(I use MS Word only to read things others have
written, and I do that as seldom as possible.)

At any rate, if your point (for some reason)
is to say that MS Word has `Edit > Go To',
then fine.  QED.  We have a winner!

> > Just as `File' often has entries for accessing
> > recently opened files, so I see it as having
> > entries for accessing other "locations".
> 
> File is already a very large menu, apart of being unrelated to moving
> in a document.

Agreed.  Other stuff there, such as the window &
frame stuff, could be moved to a `View' or other
menu.  I prefer that _none_ of the menus -
including `Edit' and `File', be a catch-all bin.

There's still room for improvement.

Re: Discoverability (was: Changes for 28)

[Richard Stallman]

[[[ To any NSA and FBI agents reading my email: please consider    ]]]
[[[ whether defending the US Constitution against all enemies,     ]]]
[[[ foreign or domestic, requires you to follow Snowden's example. ]]]

  > As a sufferer under some of those changes, I am well aware of the
  > pain that such divergences cause the users. I acknowledge that
  > sometimes those changes need to be made for sake of consistency
  > with larger refactorings. However, the fact that they do happen should
  > be viewed as a failure of engineering and not an excuse for future failures.

Emacs is older than the operating systems people use today.
(It is almost as old as the first Unix, which barely resembled
the Unix of later decades.)  It is much older than Linux, the kernel.

The oldest design elements were not designed for the uses we make of
them today.  And since we wrote those, people have developed other
areas of software which don't fit Emacs very well.  So there are good
reasons to redesign some of them.

However, people actually use Emacs, so a greatly incompatible change
in Emacs is as unhinkable as a greatly incompatible change in the New
York City subway.

We have to build new lines through the maze of underground pipes and
cables.

-- 
Dr Richard Stallman
Chief GNUisance of the GNU Project (https://gnu.org)
Founder, Free Software Foundation (https://fsf.org)
Internet Hall-of-Famer (https://internethalloffame.org)