emacs-devel
[Top][All Lists]
Advanced

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

Info tutorial is out of date


From: Drew Adams
Subject: Info tutorial is out of date
Date: Sat, 15 Jul 2006 07:44:42 -0700

I just tried the beginning of the Info tutorial again, after a lapse of a
couple decades (!). It doesn't seem to have changed much. I remembered it
with more fondness than I felt this time around. Keep in mind that, like
Info, it was created long before the Web and mice and such. Back around that
campfire, it made sense to explain in detail about nodes and menus and the
magic keys you used to get around. Nowadays, some of it seems quaint, some
seems crippling.

Here's my rant; take it for what you will. Hope it helps somehow.

The start of the tutorial teaches you `n', then `p', then `m', then `C-l',
and so on. Those keys should be regarded nowadays as shortcuts - quick
alternatives to the obvious navigational equivalents of clicking links or
using the menu-bar menu. Don't forget that the user somehow got into the
Info tutorial with no help - probably by clicking the link at the `dir'
node.

I don't even see why `C-l' is mentioned anymore, especially at the very
beginning of the tutorial. It was important back when 14K baud was a fast
transmission speed and your screen got "garbaged" (to quote the tutorial)
from time to time. You needed to learn `C-l' at the beginning, because if
your screen got garbled then you were lost in the tutorial - that was a game
in itself (much more interesting than invisible text). `C-l' is just a
vestige of the bad-ole-days - lose it.

With absolutely no instruction, a user will figure out immediately how to
move among nodes - the equivalent of `n', `p', `u', and `m', because they
*see* the corresponding links and buttons. Clicking links and buttons is a
fine way to get around, to get the info you need - at least in the
beginning. Teaching `n' and `p' does not need to take up the first several
minutes of the tutorial - it should be presented much later, perhaps in a
(brief) lesson on keyboard shortcuts.

It's OK at some point to point out that, unlike Web pages but like the
structure of a book, Info nodes are organized into a tree (menu): up, next,
and so on. But a lite version of that explanation will suffice, nowadays.
Again, all this emphasis on navigation commands is but a vestige of a time
when there were no links or buttons, when the universe was still a mouseless
void.

What it *is* important to teach up front are the important functionalities
of Info that are *not* so obvious (visible). Foremost among these are `i',
`s', and `l' (and, later, `g').

The first thing the tutorial should do is take a tour of the menu-bar menu -
that is, those menu items that are the most important. This is also the
opportunity to point out the key bindings indicated in the menu. That is the
way to introduce the shortcuts `i', `s', and `l', for instance - in passing.

Touring the menu can also be used to introduce the structure of a normal
Info manual. By that, I don't mean menus with up and next, so much as
showing that there is a table of contents (or two or three) and an index,
and how to use them effectively. And if the Info manual had a glossary (it
should, especially since it has its own jargon), then that could be
introduced too.

Users will also find the toolbar by themselves, and they may use that first
for some things (such as index lookup), because it is more obvious than the
menu-bar menu. It's worth taking a tour of the menu because it shows the
keyboard shortcuts, which the toolbar icons do not. Showing the menu-bar
menu and its shortcuts will help wean newbies from the toolbar, at least in
terms of awareness.

BTW, the help text (tooltip) for the search toolbar icon should not scare
people away by mentioning regular expressions. It should say simply `Search
the manual'. If you don't think that's enough, then it could say `Search the
manual (regexp is OK)'. None of the tooltips should use the word "file" -
they should say "manual". And we should think about changing the keyword
`File:' at the top of each node to `Manual:' - there is no reason that users
should think in terms of files here.

I'll say one more time, in passing, that an icon for deletion (X) should not
be used for quitting Info - that is a bad idea. Several other possibilities
were suggested previously (e.g. the international icon for an exit: arrow
exiting a room), and there are lots of quit icons to choose from. But that
particular X is often used for deletion, a confusion we don't want here.

The Info tutorial itself should be accessible (listed) in the menu of the
first node of the Info manual. Instead, it is only mentioned in the text of
that node, in terms of `h'. Before entering the tutorial, we should tell
users how to exit it, to get back where they were. BTW, `h' should not bring
up the tutorial, it should display a mini-version of what `C-h m' shows: a
short list of the main key bindings - about the same as what's in the
menu-bar menu, but with some explanation. There is no need to have a key
binding just to bring up the Info tutorial - people won't be doing that 30
times a day.

In general (exceptions can be made), key bindings should not be introduced
until much later, and then they should be introduced as shortcuts for
functionalities the user already knows by then. It is the functionalities
that should be on the agenda, not the keys. The emphasis is all wrong in
this respect. You lose the forest of functionalities because of all the
trees of keys.

The node `Invisible text in Emacs Info' is incomprehensible to me
("invisible text is really a part of the text"!?). Yow! Why are we telling
users about killing and yanking Info text? (I guess printing is OK.) Why is
this near the beginning of the tutorial? I really, really do not get this.

This node (`Help-Inv') will scare anyone away from using Info. It is worse
than unneeded; it is a downright nuisance. 3/4 of it is  composed of crazy
disclaimers that users won't understand ("Only the invisibility property is
affected by Visible mode" (yow!), and "When, in this tutorial, we refer to
the `Emacs' behavior, we mean the _default_ Emacs behavior" (YOW!!)). BTW,
what is the reason for the menu in this node? It doesn't seem to be used or
useful or understandable.

The rule in the tutorial should be that we don't tell people things - we
walk them through doing things. Node `Help-Inv' is not just confusing and
useless; it also violates this rule. If it were really important for users
to know about `visible-mode' and such, then the tutorial should walk them
through using it. But in this case, please don't; just get rid of this node!
This appears to be an ugly hack to enable the same tutorial to be used in
Emacs and standalone Info. Spare the user this kind of all-too-visible
bandaid.

In general, instead of introducing so many key bindings (e.g. `]'), the
tutorial should spend the user's time taking a tour of Info *functionality*.
Touring the menu-bar menu is a good way to explore the main functionalities:
show what's there and what it does. In addition to the features in the
menu-bar menu, teach SPC and DEL - that's about it. In the menu-bar menu,
teach these first: `q', `l', `s', and `g'. Why? because they're not obvious
(visible, as in links and buttons), and they're essential.

Most of what is presented now in the tutorial is either obvious or arcane.
The most important things to teach are index lookup and search. They should
be done with care, and simple regexp search can be taught here with useful
examples. It's good to teach `goto-node' (`g') too, because people will find
instructions in emails and on Web sites to go to node `Blah'.

Perhaps some of my remarks are inappropriate wrt the standalone reader - I
don't know. I used the tutorial only inside Emacs. Adjust my remarks as
needed. If the standalone Info still uses only keyboard keys, so that
everything I suggested above is irrelevant, then perhaps we need two
different tutorials now.

HTH.





reply via email to

[Prev in Thread] Current Thread [Next in Thread]