Time to Rethink Your Help Flag
by Shlomi Fish, in Editorials - Sat, Aug 10th 2002 00:00 PDT
It may come as a surprise to many of you, but sometimes, featuritis
can be a good thing. Sure, you may only use 20% or even just 10% of
the features, but, to quote Joel Spolsky, everybody uses a different
20%. Take 10 or 20 random people, and you'll get about 99%. You may
happen to face the situation in which your program has gained more
commandline arguments than GNU ls. How should you deal with the --help
switch?
Copyright notice: All reader-contributed material on freshmeat.net
is the property and responsibility of its author; for reprint rights, please contact the author
directly.
Freecell
Solver (one of my projects) is such a case. Its --help screen now
takes seven clicks to display entirely when invoked with "fc-solve -h
| less". The problem is that people like choices, but don't want to
be confused with a lot of options. If the program does nothing (or
misbehaves in the first board layout you try) and you want a quick
answer, you're not going to read through seven pages. Spolsky tends to be a bit
GUIish, but the same rule applies to commandline programs.
Several solutions have been brought forth to deal with this situation:
- The CVS
solution: --help displays a short screen giving
pointers to other help screens (--help-options, --help-command,
-H command, etc.).
- Some programs differentiate between -h and --help; -h's output
is shorter and --help's is more comprehensive.
- The RTFM solution: Refer the user to the man page, info
document, README, or online help for more information.
- The Perl
solution: --help displays part of the man page, while myprog
-man displays the entire man page (invoking the pager, too).
Here is my take on the pros and cons of each approach:
The CVS one is a bit annoying because I instinctively type "cvs
--help" and get something absolutely useless. (This could be solved
with a shell function, though).
-h and --help distinguishing is ok, but you may eventually make --help
unusable, too.
The RTFM option: Many users will not bother to read a different
source, so you may be losing some of them there. Also, if the man page
is bloated, you are back to square one.
The Perl solution is not bad as long as you make sure the relevant
parts of the man page are not bloated, and outsource things to
different man pages. Website META
Language has an interactive application for displaying and
accessing its various man pages.
My problem with Freecell Solver is that I want it be portable to Win32
and other non-Unix platforms. If you stick to Unix, you can stay with
the Perl approach and simply make sure your man pages are sane (and
that you have HTML documentation and, optionally, a PDF file).
In any case, my portable solution is a combination of the CVS and Perl
solutions. I am going to have a default CVS-like help screen, which
could later be changed to something else, using an environment
variable.
Here's what I'm going to write:
fc-solve [flags] [board_file|-]
Reads board from standard input by default or if a "-" is specified.
- If it takes too long to finish, try one of the commandline
configurations presented in --help-configs.
- If it erroneously reports a board as unsolvable, try "-to 01ABCDE".
- If the solution is too long, try running it with the "-opt" flag or
with "--method a-star".
- If you want to present the moves only, try "-m" (long notation) or
"-m -sn" (very compact).
- For a description of all the options, type "--help-all".
- For other problems, type "fc-solve --help-problems".
- To turn --help back into something more useful, read
"--help-real-help".
Contact Shlomi Fish, shlomif@vipe.technion.ac.il for more information.
|
This deals with common problems in a graceful way (of course, I'll
have to implement the other help screens). If you're asking why I
don't configure Freecell Solver so it won't have these problems,
you're asking a good question. However, the default configuration
works well for most of the boards out there, and I don't want to give
the user something more complex that may or may not work better (and
is itself a compound configuration).
I will use an environment variable named FREECELL_SOLVER_DEFAULT_HELP
(I'm a bit obsessed with maintaining namespace integrity) to specify
the default help screen. That way, the user can modify the help screen
to something more useful than the summary (which would always be
available in --help-summary). I haven't used environment variables
before, but I don't think I have a choice now.
I guess I'll have to do something regarding usability before I add
support for system threads[1]. That's why I'm planning that
the 2.7.x tree will be dedicated entirely to rethinking usability. The
factoring of the help screens would be one thing, but I'll also try to
have better documentation with more diverse formats than text files
(God bless Perl POD and DocBook), and other
such changes.
If you think human factors engineering does not apply to commandline
programs, think again. Even in the Unix world, where Real
Men(tm) and Real Women(tm) use commandline
utilities like it was their second nature, you still need to make sure
your program behaves in a sensible way. When was the last time you
managed to find a forgotten flag in the gcc man page in less than two
minutes?
Enough said.
[1] Freecell Solver is thread-safe and can task
switch but cannot be thread-enabled. If you are asking why I need to
make it thread-enabled when most Freecell users will never need to run
it on an SMP machine, my answer is: Just for fun(tm).
Author's bio:
Shlomi Fish once defined
himself as a "Programmer, Writer, Amateur Mathematician, Wannabe
Philosopher, and someone who studies in the Technion in the vain hope
of becoming an Electrical Engineer". He does not consider himself a
sane person, but is quite certain that only makes him more
interesting.
T-Shirts and Fame!
We're eager to find people interested in writing articles on
software-related topics. We're flexible on length, style, and
topic, so long as you know what you're talking about and back up
your opinions with facts. Anyone who writes an article gets a
t-shirt from ThinkGeek
in addition to 15 minutes of fame. If you think you'd like to try
your hand at it, let jeff.covey@freshmeat.net
know what you'd like to write about.
[Comments are disabled]
Comments
[»]
Some more solutions
by Mark H. Wood - Aug 22nd 2002 11:51:33
A more radical solution would be re-examining your product to see if it can
be usefully decomposed into several simpler pieces, each with its own
smaller set of options. This doesn't make sense for every program but
it's worth remembering.
Still another approach would be a more-capable help viewer. One of the
things I like about OpenVMS is the help librarian, which defines a tree
structure for help text and provides a default viewer which can be easily
linked into your program and invoked with '/help'. Texinfo is the obvious
parallel in Unixland, probably by just forking a suitable 'info' command,
but you have to deal with the possibility that 'info' isn't installed on
the box in question. On MS Windows, again there is a built-in help
application which makes larger, more comprehensive help easily navigable.
HTML help might provide a cross-platform solution, but most HTML browsers
are too heavy and you never know which one you'll have to call.
[reply]
[top]
[»]
Re: Some more solutions
by Ambrose - Aug 30th 2002 00:52:50
Inclusion of a help viewer by an OS does not guarantee that people will use
it. Some people will just use something else. Like, some (a lot?) Macintosh
programs do not use AppleGuide even though it is included. Almost all
Macintosh programs do not use Tool Tips, including some programs that are
bundled with the MacOS CD (!).
The problem with using info in X is probably because there is no
generally-available good X info viewer. Lilypond used to have a very good
X info viewer (and it probably still do), but I don't see this viewer used
anywhere else.
[reply]
[top]
[»]
X info viewer
by Hisham Muhammad - Sep 3rd 2002 16:50:16
> The problem with using info in X is
> probably because there is no
> generally-available good X info viewer.
Konqueror is a fairly decent Info viewer.
Try typing something like "info:cvs" or
"info:bison". Enjoy.
[reply]
[top]
[»]
Help
by Bruce Korb - Aug 10th 2002 16:30:25
The solution one arrives at depends upon the complexity of the
initializations required and your philosophy. In MNSHO, the usage text
should be constrained to hints about the options so that a user can get
reminders. If one needs more help than that, they need to go elsewhere to
avoid cluttering the screen for those that only need the hint.
Notwithstanding all of that, there still comes a time when there are
too many options to fit easily on a page. To cope with all of this, I
wrote a package AutoOpts that
* uses a short help form when invalid options are supplied
* provides a long help form when help is specifically
requested
* provides for visual separation of options for programs with
exceptionally long lists of options.
* the ``--more-help'' option will run the help through a pager
automatically.
An extended example of its usage can be seen here:
AutoGen
Usage
Using this package eliminates the need to mess with usage text or
parsing options or reading config files and alleviates much of the burden
of maintaining a man page.
[reply]
[top]
[»]
completion
by Magnus damm - Aug 10th 2002 13:52:20
If some sort of standard was made, then it would make it much easier to add
generic option/argument completion to the shell.
[reply]
[top]
[»]
real time examples
by Gunther Voet - Aug 10th 2002 13:22:56
I am missing a lot of real-time-examples in the help of a lot of programs.
It would be a lot easier to understand and learn how to use a command-line
utility if you can just see how it works.
For example:
If I do a tar --help I see a lot of help but not a (few) example(s).
If I would see some pointer how to decompress a file I would be working
on-the-spot with the program and I would start learning the advanced
options.
Alltough I do know how to use tar now, it would have been easier this way
instead of learning it "the hard way". There is the easy way and
the middle way ...
--
---
Watch out for ID theft; my e-mail has changed to xsrv.net because of an evil domain squatter ! ;)
[reply]
[top]
[»]
Re: real time examples
by ibbie - Aug 15th 2002 12:45:40
> I am missing a lot of real-time-examples
> in the help of a lot of programs. It
> would be a lot easier to understand and
> learn how to use a command-line utility
> if you can just see how it works.
> For example:
>
> If I do a tar --help I see a lot of help
> but not a (few) example(s).
it is possible of course to dig through the tar man pages for examples,
but i do agree. maybe have within your --help or -h some little note that
says something like "for some common examples, try 'man -examples'" and
have a simple, concise listing of what you often use the program for.
but these are just my $0.02. and i may expect change from that. (:
[reply]
[top]
[»]
Re: real time examples
by ibbie - Aug 15th 2002 12:50:47
>maybe have within your --help or
> -h some little note that says something
> like "for some common examples, try 'man
> -examples'"
i goofed. i really meant "for some common examples, try 'man
<command>-examples"
but my 'html' (i.e., < and >), as so obviously noted below the text
Posting mode, was escaped. pfft.
[reply]
[top]
[»]
Re: real time examples
by antrik - Aug 17th 2002 01:10:07
> I am missing a lot of real-time-examples
> in the help of a lot of programs. It
> would be a lot easier to understand and
> learn how to use a command-line utility
> if you can just see how it works.
That's actually the kind of information that does *not* belong into a
--help
screen usually. If you do not have an idea how the program is used, man is
for
you. The --help screen is good when you generally know the program, and
have
forgotten just that little detail...
The real problem is that many programs do not have any examples in the man
page
either :-(
[reply]
[top]
[»]
Good solution
by pevans - Aug 10th 2002 12:20:18
It's about time some serious thought were given to the problem and I like
your solution very much.
It provides the quick one-liner you may need for args, but also takes the
lost in hand and points to
more help and provides more /real/ information at the same time.
Very nice.
[reply]
[top]
[»]
--long-help? --full-help? --war-and-peace?
by Leon Brooks - Aug 10th 2002 10:07:18
Fine and good, but before you get too carried away I'd like to see
published conventions for getting full or specific kinds of help.
I'd also like to see any help for some GUI programs at all; many of them
(KDE tools are notable for this) have neither --help nor a manpage, and in
that specific case no handbook either. It would be handy to have
KDE/GNOME/etc field --help if the application does not and at least list
the KDE/GNOME/whatever options, plus the X options, and who knows what
else is possible, maybe filch out a getopts array from the application, if
it has one.
[reply]
[top]
[»]
some thoughts
by antrik - Aug 10th 2002 03:56:14
Generally, I do not consider oversized help screens that bad; at least,
you
have everthing in one place... And if you know what you are looking for,
using
|grep is just perfect :-)
The CVS version is quite OK for CVS-like programs, which have a couple of
major
operation modes, and many switches to each. Once learned that I can access
help
for a certain mode simply by using it with --help, it's actually very
nice.
(It's not too hard to learn, as many interactive command line programs
behave
similar...) The only thing I miss is an overview of available modes in
the
default help screen.
However, this version is quite annoying for programs with dozens of
different
options, that can be grouped only by topic (like dpkg, but there are
worse
examples...): it requires several runs, as I first have to find out which
one I
need. Moreover, haveing to type things like --force-help isn't very
convinient...
As for discriminating between -h and --help, I do not happen to know
any
program doing this -- which I am glad of, as I do not consider that a very
good
idea. People generally expect them to be the same. (At least I do...)
I completely agree that the RTFM version is very annoying: I hate it to
have to
go into man, info, or even /usr/doc/foo/whatever just to look up a command
line
option...
The perl version (I had that with some program just recently) is plain
stupid.
If I want to see the man-page, I can use man foo just as well... That's
akin to
the RTFM version, if not worse.
All in all, none of the presented alternatives is optimal. The best
version I
know is that of gcc: Normally just show the most important things (your
suggested default screen should do quite well), and listing all options
when
--help (of -h) is used together with -v. How about that?
In any case, I am glad to see someone considering such ergonomical issues
at
all -- that's sadly a thing quite seldom seen in the free software
world...
[reply]
[top]
[»]
Re: some thoughts
by EvilIdler - Aug 16th 2002 11:26:44
> if you know what you are looking for,
> using % |grep is just perfect :-)
grep is your friend, together with sort and uniq :)
> As for discriminating between -h and
> --help, I do not happen to know any
> program doing this -- which I am glad
> of, as I do not consider that a very
> good idea
I do know of many examples, actually. Most GNU
programs will come up with "unknown option,
use --help" if you use -h alone :/
(Try it on gawk or something)
>beginquote%
> I completely agree that the RTFM version
> is very annoying: I hate it to have to
> go into man, info, or even
> /usr/doc/foo/whatever just to look up a
> command line option...
I hate doing that with programs, too - for instance,
MPlayer now has so many options it could do away
entirely with option listing in its --help and just print
some examples of common operations (play vcd/DVD
track #n, chap #n, choose stream numbers etc.).
And tar..urgh. Thank goodness we've got cut and
paste for configure scripts, and some sane defaults
for make dist ;)
>beginquote&
> and listing all options when
> --help (of -h) is used together with -v.
> How about that?
There's an idea I should consider for my own programs..
Not that they are circulated far beyond my computer,
but it's a good idea, anyway :)
[reply]
[top]
|
