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.