Addressing Yelp Concerns

[Shaun McCance]

Hi all,

I'd like to address the Yelp concerns outlined here:

https://fedoraproject.org/wiki/Desktop_Documentation_Presentation_Options

My comments are generally geared towards Yelp 3.0, which will
be released with Gnome 3.0 in September 2010.  The design of
Yelp 3.0 is geared more towards individual documents, focusing
less on the library of installed documents.  It will be able
to locate and read help documents in DocBook, Mallard, or HTML.
It will also continue to be able to read man and info, though
I view these as bonus features, and not central to the design
of Yelp.

I do want to make sure that multiple-page HTML documents are
handled well in Yelp.  So even if you find that letting Yelp
render DocBook on the fly doesn't work for you, you may still
be able to use Yelp with pre-built HTML.

The front page of Yelp will be the Desktop Help ("User Guide"),
which will be a Mallard document.  Mallard is a new format for
topic-oriented help.  It has many advantages (which I'll gladly
talk your ear off about), but the primary selling point is that
it's designed around the idea that downstream distributors will
extend and modify upstream documents.  I hope the Fedora team
will take advantage of this and extend Gnome's Desktop Help to
better assist users.

That said, I understand that many of the documents that you're
developing and packaging aren't typical desktop or application
help files, and that you may have special requirements to fit
your users' expectations.  My goal is to help you help your
users.  I hope Yelp will be useful, but if it's not the right
fit, then do what's best for your users.  Your users trump my
ego any day.

Enough yakking.

* Fedora documents are found in Help, alongside Gnome documents,
even though these are stand-alone documents generally not coupled
to any particular application and are therefore a different kind
of documentation from what's generally provided in help and what
users therefore expect to find there.

Yelp is moving away from the focus on all installed documents,
although this will still be available.  Some clever categorization
could help this.  There is, of course, nothing that precludes you
from continuing to put links in the application menu to documents
that are displayed in Yelp.

* Yelp has some size limitations. At this time it is not entirely
clear whether this is a limitation on some specific item such as
index entries or an absolute document size limitation.

There are no real size limitations, except possibly the recursion
limits in libxml2, although I doubt you're hitting those.  This
is probably just a symptom of the speed issue below.

* Since yelp handles rendering, there is no control over document
style.

I generally view this as an advantage.  Fiddling with design is
not something authors should spend their time on.  When they do,
they often create something blingier, but decidedly less readable.

That said, I understand the desire to brand a set of documents.
I'm entirely open to having some sort of XSLT "themes" that can
be installed and referenced by documents.  It's something I've
toyed with in the past.  But nobody's expressed interest before,
so it never became a priority.

* Yelp does not produce document indices when requested.

True, although that doesn't mean it couldn't.  That's clearly an
important feature for Fedora, so I can bump it up on the priority
list.

* Yelp can be slow. For larger documents, very slow. Breaking the
document into multiple files does not help.

DocBook is an inherently single-file format.  I assume this is
referring to using SYSTEM entities or XInclude to slurp other
files in.  All of that is handled by libxml2.  As far as Yelp
is concerned, it's reading one big file.

So when I first took over Yelp, I managed to get a lot of very
big performance improvements in.  Then I took a hiatus.  Some
of my improvements got lost, and a few I had planned never got
done.

We can make Yelp noticeably faster.  I know where most of the
bottlenecks are.  Obviously, though, there's no way on-the-fly
transformation will ever be as fast as reading an HTML file.
It's a question of what's fast enough.

* Yelp does not display the Publican-produced revision history.

This I can address, even in the 2.30 timeframe if you want.
Basically, Yelp's interpretation of DocBook revision history
is a product of the way Sun was using it to satisfy, to the
letter, the requirements of the GFDL.  It's a quirky legacy
behavior, and we can't throw it away entirely, but we can
adapt to what Publican is doing.

* Publican cannot currently package multiple languages, and at this
time, it appears it will not address yelp packaging in the future.

Packaging a document for Yelp 3.0 is easy.  You just have to
put it in a location Yelp understands.  No ScrollKeeper or
any registration procedures.  If Publican can't change its
installation directory, Yelp may be able to adapt to it.

* Yelp addresses only Gnome and does not help other desktops.

One of the big things happening in Yelp 3.0 is that we're
splitting the transformation core into a separate library,
libyelp.  The XFCE team has already expressed an interest
in building their own help viewer on top of libyelp.

Of course, I understand that KDE is important.  I've been
talking to the KDE team, and I hope we can finally come to
a consensus on a common help system.  That way you can just
install your documents to a common location, and Gnome, KDE,
and XFCE would all pick it up.

* All languages are installed, whether or not needed. The installed
size in all languages for our longer documents is hundreds of megabytes.

I don't see how this has anything to do with Yelp.  This
is a matter of how you package your files.  Are those pesky
OMF files keeping you from doing language packs properly?
I'm fairly certain there's nothing in the 3.0 designs that
will force this.  The Ubuntu team is also interested in
doing language packs for documentation, so I want to get
this right.

* Package maintenance has a high overhead; the package maintainer
must update the package any time any translation team needs to make
a correction or update.

Again, I'm not sure what this has to do with Yelp.  Please
let me know what Yelp can do better to help you here.

* Packages for larger documents may be hundreds of megabytes. Each
language may (should) have localised images. Images can take up
substantial space. Limiting images is not an option as images are
useful for various aspects of learning and documentation.

Right, so this is the language pack thing again.  I will say
that one of the nice things in Yelp 3.0 is that it looks up
everything according to a path, and can fall back to content
elsewhere in the path.  This includes images.  So if you have
both a "C" version and a localized version of a document, and
you have non-localized images (common for including icons in
documentation), you don't need to install those images with
the localized document.

I'm also working on allowing the XML files to be compressed
on disk.  This doesn't help the package size, but it does
help the install size of the package.

In the end, though, if you have huge documents with lots of
translations, you probably want to do some sort of language
packs.  I think this is mostly a packaging and distribution
problem, so the ball's in your court.  But I want to make
sure that Yelp isn't putting up extra roadblocks, so please
let me know if it's making this difficult.


Thanks for your time; I know this email was long.  And
thanks to everybody who's been bringing these concerns
to my attention.  I'm trying to be more involved with
downstream, but there's a lot to keep up with.

--
Shaun