bug#8353: 24.0.50; Header of *Apropos* buffer needs to explain `(SCORE)'

bug#8353: 24.0.50; Header of *Apropos* buffer needs to explain `(SCORE)'

[Drew Adams]

(setq apropos-sort-by-scores 'verbose)
 
C-h a forward buffer char RET
 
The buffer header needs to explain what the parenthesized numbers mean,
e.g. (804).  First, explain that these are scores.  Second, explain what
they mean and how hits are scored.
 
It makes no sense to introduce a new feature like this without
describing it to users.

In GNU Emacs 24.0.50.1 (i386-mingw-nt5.1.2600)
 of 2011-03-21 on 3249CTO
Windowing system distributor `Microsoft Corp.', version 5.1.2600
configured using `configure --with-gcc (4.5) --no-opt --cflags
-Ic:/imagesupport/include'
 

bug#8353: 24.0.50; Header of *Apropos* buffer needs to explain `(SCORE)'

[Lars Ingebrigtsen]

"Drew Adams" <drew.adams@oracle.com> writes:

> (setq apropos-sort-by-scores 'verbose)
>
> C-h a forward buffer char RET
>
> The buffer header needs to explain what the parenthesized numbers mean,
> e.g. (804).  First, explain that these are scores.

The documentation of the variable says that scores are displayed, so I
don't think it's necessary to say that.

>  Second, explain what they mean and how hits are scored.

I think that's pretty irrelevant.  I think everybody understands that
higher scores are "better".  And the way the score is derived is liable
to change.

-- 
(domestic pets only, the antidote for overdose, milk.)
  bloggy blog http://lars.ingebrigtsen.no/

bug#8353: 24.0.50; Header of *Apropos* buffer needs to explain `(SCORE)'

[Drew Adams]

> > (setq apropos-sort-by-scores 'verbose)
> >
> > C-h a forward buffer char RET
> >
> > The buffer header needs to explain what the parenthesized numbers
> > mean, e.g. (804).  First, explain that these are scores.
> 
> The documentation of the variable says that scores are displayed, so
> I don't think it's necessary to say that.

Users do not necessarily see the variable or know anything about
it!  This is about the apropos output buffer.  We show them a
number in parens, without saying anything about what it means.
That is really bad user interface etiquette.

If this is not supposed to be meaningful to users then REMOVE it
from the UI - don't show the scores.  If showing this is supposed
to help users, then let them know what these numbers mean.

This should be a no-brainer.

> >  Second, explain what they mean and how hits are scored.
> 
> I think that's pretty irrelevant.

Then remove them.  If you show them to users then introduce/explain
them.

> I think everybody understands that higher scores are "better".

If that were the case there there would be NO need for this
variable and NO need to show the scores.  The fact that we let
users sort differently shows that scores are meaningful and 
higher is not necessarily better, in terms of what the user
is looking for or how s?he wants the hits presented.

> And the way the score is derived is liable to change.

Then the info describing the feature would be updated 
accordingly.  You cannot just throw something like this out
there in a UI and offer no information about what it is.