Addressing Yelp Concerns

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