Re: How to make Emacs popular again.

[Eli Zaretskii]

> Date: Sat, 26 Sep 2020 20:36:51 +0300
> From: Jean Louis <bugs@rcdrun.com>
> Cc: jamtlu@gmail.com, emacs-devel@gnu.org
> 
> * Eli Zaretskii <eliz@gnu.org> [2020-09-26 19:55]:
> > You cannot learn this stuff by walking around the UI and reading the
> > tooltips.  It's unrealistic.  Those tooltips assume some minimal
> > knowledge of the terminology and the UI elements, which are described
> > in the tutorial and in the first chapter of the manual.
> 
> It is your opinion.

Each one of us expresses his or her own opinions.  It's a trivium.

> I tried finding what should undecided-unix mean, and I cannot find, I
> just found that "unix" is alias for "undecided-unix".

Type "C-h i m emacs RET i undecided RET", and read there.

> Does the tooltip assume that only experienced user, in this case,
> experienced developer is to know what it means?!

Not "experienced", but one who have read some minimal introductory
material about the Emacs UI, and/or have learned how to use the manual
to search for (as yet) unknown concepts.

> You say that it is described in the tutorial and in the first chapter
> of the manual, and I gave you example with one term "undecided-unix"
> and it is not described or defined.

The tutorial describes the main parts of the mode-line display.  The
section "Mode Line", which is the 3rd section of the 1st chapter of
the manual, describes the mode line in more detail, including the
"coding-system" parts.

> It could be defined in the source code, but tooltip should not be
> written with such assumptions

It isn't.

> tooltip should help the user understand what is it.

It does.  It just doesn't (and cannot) explain everything, because a
tooltip is a small widget which cannot display a very long text, and
because clicking on the text in a tooltip is impossible, at least in
some/most toolkits we use.

> In general tooltips are good. I just say there is space for improvement.

There's always space for improvement, and practical suggestions for
improvements are welcome.  Such practical suggestions need to
recognize and observe the limitations of a tooltip, as well as the
limitations of the attention span of a typical user -- especially a
newcomer, because newcomers frequently come to Emacs to do some
relatively small job, and cannot invest long hours in following
hyperlinks.

> > Making each term a hyperlink that leads to its description, then
> > each term in that description a hyperlink, and so on and so forth,
> > will in effect take the user down a huge rabbit hole.
> 
> Is not that complex, maybe you should try wordnut package

I never said it was complex.  You are missing my point.

> > Users who need to actually do something useful with their time, not
> > just follow hyperlinks, will very quickly lose patience and stop
> > following.
> 
> I just have a feeling you got that opinion too subjectively. In my
> opinion, every word should be reachable

So we disagree.  That's fine.  Others can read your opinion and mine,
and make up their own minds.  Let's see how they respond to these
ideas.

> > We already have that: the Glossary section of the manual.  But I don't
> > think taking the user there for each non-trivial word in our
> > documentation is a practical idea, or even a good one.
> 
> If user cannot understand the word, then cannot understand the
> sentence, so how it can be good to bring users to misunderstandings? I
> don't get the logic.

The logic is that when they find some term that is not clear, and the
text there doesn't have a hyperlink to where that term is described in
more detail (there usually is), then the user should go to the
Glossary and search the term there.

> > > I wanted to find out about "Search Files..." so the menu option is
> > > pretty clear, it helps me search files, but then description about
> > > "Search files" does not even mention the word "search".
> > 
> > Unsurprisingly, the doc string assumes the user already knows what
> > Grep is.  So it doesn't say "search", because that's what Grep stands
> > for.
> 
> >From the new user viewpoint I cannot possibly agree with that
> explanation. Descriptions of menus should be accessible and
> understandable for users especially from a new user viewpoint.

Once again, there are limitations of what can be usefully said in a
short menu entry and its tooltip.  If you have practical suggestions
for how to use up the available screen estate better in that case,
please propose how to improve the wording we have there.

> > Doc strings are in generally terse; if you want more details,
> > including background etc, you need to read the description of the
> > commands in the user manual.  There's a 95-line section there about
> > M-x grep and related commands.
> 
> I am not speaking of myself Eli. I am speaking of new user viewpoint.

So am I.

> Even "Search files..." is not well described. You cannot possibly
> design any interface for new user with experienced user viewpoint.

Once again, the menus assume a certain level of understanding and
expectations.  You are claiming that those assumptions are incorrect,
but the solutions you propose are simply not practical, as they ignore
the basic limitations of the screen estate we have for this, and would
make the doc strings impractically verbose and full of loosely-related
background information.  Our policy is to leave the extra information
for the manual.

> The "Search files" with grep would actually mean to search the files
> containing certain term.

The tooltip for that menu item says:

  Search files for strings or regexps (with Grep)

which is basically what you say above.

> But for new user, "Search files" would probably mean to find those
> files named "Alice-Homework.txt" or something like that.

See above.

> It is good for developers to think more from a new user viewpoint.

Agreed.  We do.

> We speak here more of principles of design of the interface and
> descriptions. Practical implementations may come later.

Emacs already does have the practical implementations.  They are
well-thought and are being constantly improved.  There's no need to
start from scratch, as what we have already is a reasonably good and
newbie-friendly UI.  It is newbie-friendly because the Emacs
developers of past and present invest a lot of efforts into making it
so.