Re: Improved help from minibuffer prompts

[Eli Zaretskii]

> From: "Drew Adams" <address@hidden>
> Date: Tue, 20 Apr 2004 16:13:04 -0700
> 
> My point here was that the key sequence that calls up help when inputting an
> arg could just (generically) echo "Use `C-h f <command-name-here>' for more
> information".

That could cut it, I suppose, assuming (unrealistically) that most of
the doc strings do a job that's good enough, but I think that giving a
specific help for the argument being prompted for is still better.  It
is better because the info presented to the user is shorter and
specifically targets what the user presumably is concerned about at
the time she presses the help key: what kind of input Emacs expects.

> My point here is that if the input-arg help does *not* include the whole doc
> string, then it only goes so far toward helping you use & learn about the
> command. That's OK as far as it goes, but you might get the impression that
> you've learned it all, and miss out on some important functionality.

When I want a help on a specific argument, I don't care much about the
rest of the doc string, and don't assume I know everything about the
command after reading only about the meaning of the specific argument
in question.

In general, I think we should assume that if the user invoked a
command, she already knows pretty much about that command, i.e. she
already read its documentation at least once.  We could provide a
link to the full doc string in the text we pop up to describe the
currently prompted-for arg, in case that assumption is false, but
there's no need, IMHO, to assume that the user needs to see all that
info to begin with.

As a general rule, showing too much information when there's a high
probability that the user wants to see only its small portion is a bad
idea, IMO.  For example, don't you get annoyed by all those answering
machines installed by government organizations and large firms to
respond to their support telephone lines, which force you to hear lots
of info before you get to the point?  Many times, after hearing a lot
of info that is only tangentially related to what I'm up to frustrates
me so much that I disconnect in disguise.  Similar results could
follow if we show users too much information when they need only its
small portion.

> 1. If the arg-input help does *not* give you the whole doc string (directly
> or indirectly), then:
> 
>  . It's not worth it.
>  . It might lead you to miss out on important info in the doc string.

I can understand the second part, but I don't understand the first:
why ``not worth it''?  If I'm looking specifically for what I could
type at the current prompt, I think it's worth its text in gold.

> > Someone saw room for improvement, but I don't want to say I am certain
> > it is important.  Perhaps things are good enough as they are.
> 
> IMO, they are. #2 and #3 at the top are key: good doc strings, good prompts
> (and commands that don't require understanding complex input args).

I disagree here: there's too little real estate in the minibuffer to
show a prompt that explains the possible inputs in enough detail, at
least not in all cases.  Giving the temporarily confused help that is
focused on the specific task they are confused about is IMHO A Good
Thing.