[RFC] Online Help Systems

[Sean Wheller]

Hello,

As we all know many people are targeting yelp/scrollkeeper as technologies by 
which users will be able to access the Ubuntu Documents. This is fine for now 
since Ubuntu currently only ships a GNOME Desktop. However, I doubt it will  
always remain this way and wish to warn against lockin to the GNOME Help 
system. My reasoning follows, I would appreciate thoughts, feedback or 
possible solutions I may have overlooked.

John Levin has given us indication that people are talking about smaller 
desktops:

" On the subject of desktops and compatibility, please don't forget the
 smaller desktops like IceWM, XFCE etc. There's been a number of threads
 on the user list about ubuntu on lower spec machines, where Gnome is
 just too heavy. Whether there is an 'official' ubuntu-lite or not, it
 seems a safe bet that there will be significant numbers of
 non-gnome/kde users.

HTML is the simplest answer for covering all desktops."

And a birdie told me that somebody is porting "UserLinux" to Ubuntu.

As some of you may know, I have been concerned about making the documentation 
src as broadly compatible as possible and made scatterred mention of this 
across the list and on IRC. Most recently I had a conversation with 'plovs' 
on this subject in IRC.

In evaluating ways to do things under yelp/scrollkeeper I have found a number 
of problems that IMO are cause for concern.

1. Limited suport for some very powerful Docbook features. For example: 
Glossary, Bibliography, Index, Profiling.
2. Limited ability to brand and customize help features.
3. Poorly formatted display of xrefs, a key cross-reference mechanism.
4. Implimentation of external cross references using ghelp:fooapp is 
incompatible with HTML and FO outputs.

My concern with these issues is point-to-point:
1. The unsupported features limit our ability to produce comprehensive works 
and to publish them in both electronic and print formats. To do so we would 
need to perform an extensive amount of pre-processing prior to transformation 
to presentational targets.

2. As far as I can see, other than adding a logo here an there, there is not a 
great deal of flexability to customize yelps output. OK, some will say we can 
take yelp source and make the changes we want then recompile it, but I think 
this is not our core focus. We hardly seem to be adding to the docs, let 
alone enhancing yelp. If yelp was the only way to access help I would say we 
have no choice, but that is not the case.

3. A small problem that could probably be fixed in the short-term is that yelp 
does not render xrefs properly.

4. The method used for implimentation of cross document references in GNOME 
requires a combination of Yelp+ScrollKeeper. When calling an external 
resource the attribute value supplied is something like this 
url="ghelp:fooapp". naturally this does not work except under yelp and 
scrollkeeper. So any trarget presentational formats would contain broken 
links.

In view of these problems and the high probability that Ubuntu will support 
other desktops, I would like to refrain from using anyting that causes lockin 
to GNOME. Please note, I am not saying we don't support GNOME. I am saying 
that the docs must run across desktops, GNOME included.

I realize that people are are familiar and comfortable with yelp. This may 
cause some people to say that yelp is the help viewer standard for GNOME and 
we should not discard its use. I therefore ask people to consider the 
following.

In my opinion, it is not yelp or any other viewer that makes a good help 
system. It is the content contained in the documents that is responsible for 
this. What users use is really a secondary thought when you consider that all 
they want is to be able to access, browse, search and print information. For 
all they care you can let them use a simple web browser. Who cares about yelp 
or khelpcenter when you want to do or fix something.

Having said all this, I would therefore like to motion that we target chunked 
HTML/XHTML as the target format of choice for Ubuntu Documents. The 
advantages are as follows:

1. Ability t use all docbook features without regard to platform or user agent 
technologies.

2. Ability to customize as much as we need or desire.

3. Portability across desktops.

4. Flexability in deployment under Web based applications (locahost or central 
server)

5. Reduced technology lockin.


Your thoughts are appreciated.

-- 
Sean Wheller
Technical Author
sean at inwords.co.za
http://www.inwords.co.za
Registered Linux User #375355
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 189 bytes
Desc: not available
URL: <https://lists.ubuntu.com/archives/ubuntu-doc/attachments/20050111/89b6abf1/attachment.pgp>