Better GNOME help facilities [Was: Re: More traditional GNOME behavior [Was: Get nautilus OFF OF MY SYSTEM!!!]]

[Bret Mogilefsky <mogul-gnome gelatinous com>]

On Tue, May 08, 2001 at 09:53:53AM -0600, Josh rigler wrote:
> The bulk of my frustration however stemmed from the fact/opinion that,
> as much of the GNOME development effort gets further along (including
> base GNOME and derivatives like Sawfish), it seems more and more
> difficult to find adequate documentation.  The "--help" options just
> don't cut it most of the time.

I agree and disagree with you... I agree that it's not easy enough to know
what you're looking for help with, but I disagree because the --help
options have never been a substitute for reading the manual.  In my
old-school Unix mind, this is the order you go through: 
			  app --help 
			  man app
			  info app

The --help option in my experience has *never* given full documentation,
and usually just consists of what the command-line parameters are... Most
of which won't be immediately useful for most of the GUI stuff we're
talking about.  Man pages are good, but are flat and become unwieldly if
there's a lot of documentation.  Long ago GNU programs started using the
info format to distribute a hypertext manual, which is much better, but
most people find it too bothersome to use... which brings us to your next
gripe.

> Now I do realize that the documenting efforts so far are much better
> than what a typical MS/Macintosh user might expect, but they are not
> what I've come to expect from opensource projects in the past.  The
> simple issue of my not understanding exactly where GNOME stops and
> Sawfish starts should be proof enough of that, because I did make an
> effort to find such documentation on my system, and failed!  This is
> exacerbated when the particular problem I'm trying to solve involves
> getting the proper program to display the help pages (since so many of
> GNOME's documentation is in html, not more traditional man, info, or
> HOWTO pages).

OK, but you're missing the fact that there is a general help interface.
This is how you find help on stuff in Gnome; it's not perfect.  If
you start up the Gnome Help Browser (gnome-help-browser, it should be in
your menus) you get a top-level menu pointing to the Gnome User's Guide,
and all the other documentation in the system whether in man or info
format.  Similar functionality exists in Nautilus, using the "Help" tab at
the left.  The third section in the User's Guide TOC is "Window Managers
and GNOME".  Now granted, this is only going to tell you about the fact
that Sawfish is separate, but it will get you going.  At this point you'll
go looking for sawfish docs, and find them in the info section from the
top help page.

People, this is where gnome-help-browser and Nautilus fail: NONE OF THIS IS
SEARCHABLE.  This is baseline functionality.  Manuals are great for someone
who's never used the software before, but when you need help you have to
search for the thing giving you pain.  Even man pages have some basic
searchability that is lost by using these help browsers.  Info-format
documentation is meant to be searched, and again, that functionality is
lost here.  It embarrasses me when I evangelize Gnome to people at my
office and have to admit that there's no way to use this pretty help
browser to search the documents it refers to.

Assuming searching works, the next thing to do is to make some of the
manual contents alive... For example, if you're using a Gnome-compliant
window manager, there should be a link in that section of the User's Guide
that says "take me to the manual for my window manager, XXXXXX" that goes
to the right place no matter which one you're using.  If you're not using a
Gnome-compliant window manager, it should say, "Sorry, you're not using
one, but here's a link to the place in the Control Center where you can
change it to one of the following nicely-supported ones."  We have help,
but we don't have context-sensitive help.  In my mind this is one of the
main things keeping Gnome off of my mom's desk.  Windows help may suck, but
there are certain things it does right... Can we do better than that for
2.0?


Bret