Re: The minibuffer vs. Dialog Boxes (Re: Making XEmacs be more up-to-date)

["Eli Zaretskii" <eliz@is.elta.co.il>]

> From: Brady Montz <bradym@balestra.org>
> Date: 22 Apr 2002 09:54:09 -0700
> 
> I see very little in the UI which makes these various
> options obvious, and the biggest single struggle I have helping emacs
> beginners is helping them learn how to find out
> information. Currently, people have suggested three ways to get to
> sort-paragraph from sort-lines: open sort.el (my fallback approach),
> apropos, or Info-elisp-ref, and putting xrefs in the doc strings.

These all (and more) are under "Help" in the menu bar.

If you are saying the the menu bar is not obvious enough, then please
suggest practical ways to make that more obvious.  The problem with
help functions is that, IMO, a user should generally request help
explicitly, or make some sign that she needs help.  Otherwise, if we
stick the help info into her face when it is not requested, we risk
ending up with the equivalent of that annoying MSWord-style paper
clip.  So if the menu bar is not enough, please suggest the ways Emacs
should use to decide that the user needs help (and perhaps what kind
of help as well).

> Now, as for more xrefs in the docstring. Not good. Bad. For one thing,
> they are too likely to get stale.

I think documentation runs the risk of becoming stale no matter how
you organize it--separate from the stuff it refers to or not.  You
cannot avoid the maintenance burden here.

> Back to my example. So far, three people have suggested three
> ways. First, not all of these ways work for every function (for
> example, C-h C-f gnus just failed for me)

Is "C-h C-f" supposed to show the Info node for a command you type?
If so, the equivalent command works for me in Emacs with gnus.

> nor for every situation
> (for example, starting from a keybinding instead of a function name)

"C-h K" does that for me in Emacs.

> none of them are apparant from the UI

Help->More Manuals->Find Key in Manual and Find Command in Manual do
that in Emacs.

> So, time to experiment with some code. I'd like to know any idioms
> that people have for finding information. In particular, I'd like to
> know the situations in which those idioms are used.

It depends on what you are looking for, I think.  If the goal is to
find quickly a description of some subject, then a keyword-based
search (a user types several keywords, and Emacs finds the appropriate
documentation) is IMHO the best.  The `i' command in Info gets pretty
close to that (it's normally the first or second method I try when
looking for things).

This could be inappropriate for people who want an introduction to
some broad issue, though.

Another idea is to try the hierarchical approach: a user is asked a
series of questions about the subject she wants to read about, which
(the questions) progress from general to more and more specific, until
the subject is determined and its documentation displayed.  With each
question, the user is given a small number (like 4) of possible
responses that should narrow the search in the next stage.  Some
knowledge bases on the net are organized in such ways.

> For example,
> knowing a fair bit about emacs, I generally start with my comfortable
> turf which is a known similar function, then I apropos, search the
> info pages or source, or a known phrase (generally with nice emacs
> terms like buffers, regions, yank, that are stirring up so much
> trouble elsewhere on this thread :)), and I google search.

A suggestion for a procedure that uses Emacs facilities in a certain
order (derived from experience) can be found in the node "Help" of
the latest Emacs user manual (shipped with Emacs 21.1).