> Date: Sat, 26 Sep 2020 21:58:24 +0300
> From: Jean Louis <bugs@rcdrun.com>
> Cc: jamtlu@gmail.com, emacs-devel@gnu.org
>
> > > It is your opinion.
> >
> > Each one of us expresses his or her own opinions.  It's a trivium.
>
> Sure, but we talk about users, so to say that one cannot learn the
> stuff in general, should be supported by some kind of a survey.

Same is true for your opinions.

> The fact is right now is that not every tooltip is usable

"Not usable" in your opinion.  I disagree.

> So it will happen to new user to get confused. Users expect tooltips
> to describe the function, and description shall be made better
> understandable.

You (and anyone else) are welcome to suggest improvements.  But the
fact that there's place for improvement doesn't yet mean that what we
have is unusable or confusing.

> > > 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.
>
> I did not find the definition for undecided-unix by following your
> example. That it is alias, does not define it.

I don't think I understand why.  Quote:

     The coding systems ‘unix’, ‘dos’, and ‘mac’ are aliases for
  ‘undecided-unix’, ‘undecided-dos’, and ‘undecided-mac’, respectively.
  These coding systems specify only the end-of-line conversion, and leave
  the character code conversion to be deduced from the text itself.

(The previous text explains what is "end-of-line conversion".)

> > 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.
>
> For that group of people I disagree they need any tooltip
> then. Tooltip is for users to understand it, it is not for Emacs UI
> skilled people. It is for unskilled.

I didn't say "skilled".  Users aren't divided into those who know
nothing and those who are "skilled".  There are many degrees of gray
in between.

> > 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.
>
> Sure, you know it. But does it say anywhere? Does it guide the user?

Having a glossary is one of the basic traits of any serious
publication.  Not unlike having a TOC.  I expect readers to know about
that and actively search for it.

> > 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.
>
> I think that general principles shall be set first, as to improve
> wording, there are so many that could be improved, the descriptions
> should not be written in first place that do not describe it
> meaningfully. So I do not speak of a specific bug, I speak of general
> flaws hindering understanding for users.

There are no "general flaws" in this context.  These aspects of Emacs
documentation and UI were worked on for many years by many talented
people.  So any flaws are likely specific and not general.

In any case, speaking about "general flaws" without any concrete
details and concrete proposals for specific menu items or tooltips is
not a very useful investment of our time.  So if this is what you
intend to talk about, I'm afraid I won't be able to continue
participating in this thread.

> > > I am not speaking of myself Eli. I am speaking of new user viewpoint.
> >
> > So am I.
>
> Alright, then your viewpoint for new users is way advanced.

Your words.  I disagree.

> So something like:
>
> Search files (Grep...) is using the external shell command "grep" that
> searches the named input files for lines containing a match to the
> given pattern.

That is basically what the tooltip already says.