Addressing Yelp Concerns

[Paul W. Frields]

On Sun, Dec 13, 2009 at 08:14:21PM -0600, Shaun McCance wrote:
> On Fri, 2009-12-11 at 10:06 -0500, John J. McDonough wrote:
> > On Thu, 2009-12-10 at 22:01 -0600, Shaun McCance wrote:
> > > the primary selling point is that
> > > it's designed around the idea that downstream distributors will
> > > extend and modify upstream documents.
> > 
> > Now this sounds like a good idea
> 
> So I understand the reluctance to deal with yet another format.
> There certainly are more than enough of them out there.  But I
> think it's important to stress that Mallard is in a different
> class than any other format you're using.  The only other open
> format that's doing similar things is DITA.
> 
> Aside from the point that Mallard is much easier to deal with,
> its primary strength over DITA is that guides ("topic maps" in
> DITA lingo) are dynamic, responding to what's installed.
> 
> This was an intentional design goal from the outset to help us
> finally solve two related cases: distro additions to upstream
> documents and plugin documentation.

>From the standpoint of the casual user, the Mallard based docs are
more functional and usable because they respond to natural questions:
"How do I do <X>?" instead of the old-style "Intro/Topic1/Topic2..."
organization which often requires the user to browse for longer to get
the answer to a question.

[...snip...]
> > > * 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.
> > 
> > Clearly it doesn't have anything to do with Yelp.  This has to do with
> > decisions about how we want to trade off disk footprint for user
> > flexibility.  There are limitations to RPM that constrain us here, and I
> > don't see APT as being any different.  Indeed, this is a place where
> > Yelp might have a leg up over HTML.
> 
> So it seems to me (said naively) that if one knows certain things
> about the packages one is installing, one can build an installer
> that's a bit smarter and more user-friendly.  Overcome limitations
> in the package system with package name conventions or some such.
> 
> Perhaps somebody could build a specialized Fedora documentation
> viewer using libyelp and PackageKit that can find an install
> documentation for the user.  Or maybe we can build that into
> Yelp.  Any UX people around that could create some work flows
> or mockups?  I think this would be interesting to look into.

Perhaps this could be done by having documentation RPMs advertise a
capability, which PackageKit could then locate and install in a manner
similar to codecs and fonts.

> > > * 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.
> > 
> > Isn't this pretty close to where it is now?  Cant we just add a doc,
> > then add an OMF, and away we go?  Am I forgetting something?
> 
> Yelp 2 can find the right document for your language based on
> a path.  But once it finds it, it's stuck in that directory.
> In Yelp 3, subresources (like images) are located according
> to this path as well.  (This was a pretty critical feature
> for getting Mallard right.)

So images and other common bits could still be located based on a
relative path, correct?  Such as "../../../images/foobar.png"?

-- 
Paul W. Frields                                http://paul.frields.org/
  gpg fingerprint: 3DA6 A0AC 6D58 FEC4 0233  5906 ACDB C937 BD11 3717
  http://redhat.com/   -  -  -  -   http://pfrields.fedorapeople.org/
  irc.freenode.net: stickster @ #fedora-docs, #fedora-devel, #fredlug