possible documentation viewer?

[Jeff Schering]

On 6/3/05, Jeff Waugh <jeff.waugh at ubuntu.com> wrote:
> <quote who="Sean Wheller">
> 
> > Here is a wish list from Yelp:
> > 1. Easily customizable main page.
> > 2. Easily customizable gentexts.
> > 3. Easily customizable formatting
> > 4. Support for Glossary
> > 5. Support for Bibliography
> > 6. Support for Docbook Profiling
> > 7. Support for qanda sets
> > 8. Search and Index functionality
> > 9. Cross Desktop inter document referencing (ghelp:) is to gnome binding
> > 10. Support for Docbook 4.3 (mostly a scrollkeeper problem)
> > ... others may have more, but these are our main requirements.
> 
> Please provide rationales for the above features. Most of them are "useful",
> not "showstopper".
> 
> - Jeff
> 

>From a user's point of view, there are a couple of showstoppers.

1. Search is a showstopper. The purpose of yelp is to provide
information to users of GNOME-based apps. The first thing a user wants
to do after opening yelp, is find the informationn that he or she
wants. In an ideal world, the menus provided in yelp would lead the
user directly to the applicable page. Sometimes this works, but most
times it does not. You can spend a long time wandering through the
maze, or you can enter a couple of search terms and only spend a short
time wandering. Also, users expect a search function in a help app,
especially those coming from Windows. Windows help has had a search
function since day one, and yelp needs it too. Firefox help has
search. OpenOffice.org help has search. KDE Help Center has search.
Search is a standard feature, and yelp doesn't have it.

2. Although it isn't on the above list, Printing is a showstopper. For
better or for worse, users frequently want to print out a page or two,
or even an entire help topic, so that they can read it on paper. Maybe
they don't like reading from the screen, or maybe they want to browse
a doc on the train to work. Whatever the reason, users want it.
Browsers have print functions. Firefox help has a print function.
OpenOffice.org help has a print function. KDE Help Center has a print
function. Printing is a standard feature, and yelp doesn't have it.

3. QandA sets is a showstopper. Whatever you think of FAQs, users like
them. Most users turn to the help system because they have a problem,
and a well-designed FAQ is an expedient route to answers. A FAQ is
quite often used even before a search. If we can't do QandA sets in
yelp, then we can't do them anywhere, at least not if we want yelp to
use the same DocBook source that our other tools use.

The users of Ubuntu are the gods, not us. If a user can't find out how
to use Ubuntu Linux, then he will go back to Windows. It's as simple
as that. If the Ubuntu help system does not have the standard features
of other help systems, then the Ubuntu help system is a substandard
system. Substandard systems do not attract new users. Substandard
systems drive current users away. Nobody wants that.

Ubuntu Bugzilla and GNOME Bugzilla show that over the past couple of
years, search and print have been requested from time to time, and so
far the response from the devels is, essentially, "whatever". Is it
any wonder that the docteam wants to develop its own help browser that
has the standard, normal features our customers want, need, and
expect?

FWIW, I can't help but point out that it's more useful to create a pdf
from DocBook source and view it in xpdf than it is to view the DocBook
source directly in yelp, even though xpdf is at the low end of the
user-friendly scale.

Finally, if we can't use glossary, bibliography, profiling and other
DocBook features in yelp, then it becomes difficult (if not
impossible) to use them in other presentation formats without creating
a special and separate DocBook source file just for yelp. Yelp is the
weak link, and it is forcing us to use the lowest common denominator
when it comes to DocBook capabilities.

>From a documentation point of view, there are two options:
1. fix yelp so that it has the standard features that users expect
2. create our own help system

Option 1 doesn't seem to be working out for us.
 
Cheers,
Jeff S.

-- 
GPG Key: 1024D/F23C67E8 2005-02-20 Jeff Schering <jeffschering at gmail.com>