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

From: Drew Adams <[email-masked]>
Date: Mon, 10 Feb 2014 10:40:08 -0800 (PST)

> > (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.