Desktop Documentation Presentation Options

Over the past few months, there has been considerable discussion over the display of documentation on the desktop, and the delivery of that content. This page is intended to capture some of the presentation options; delivery is a separate issue.

Edit this page
Please add additional advantages or disadvantages you see, as well as alternative approaches that may make sense

Yelp

Currently, the Release Notes and About Fedora are displayed using Yelp and are delivered together in a single package. The user selects Help from the System menu and a window opens showing the title and short description of a number of topics including the Release Notes and About Fedora. Depending on what applications the user has installed, there may be other topics displayed.

Clicking on a title opens the document in the same window in an html-like fashion.

Both the opening screen and the document are displayed in the language chosen by the user at logon time.

Characteristics of Yelp

Yelp is a straightforward, easy to use model. Fedora Project provided documentation is integrated with other help in a very user friendly fashion. Presentation of all documents is consistent. Yelp is relatively slow, performance deteriorating rapidly with document size.

Requirements for Yelp

1. Yelp documents are in XML. Publican-produced XML is perfectly adequate.
2. Each language requires an "omf" file to connect the language to the appropriate document. Local language content of the omf is taken entirely from the Publican strings, so no additional translation is required. See Example .omf for an example.

Advantages

1. Fedora documents are found in Help, alongside Gnome documents, where the user can easily find them
2. Yelp handles rendering, so there are no issues with style sheets, branding, etc,
3. We have long experience with yelp so there are few surprises
4. User automatically gets the document in his local language if it is available

Disadvantages

1. 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.
2. 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
3. Since yelp handles rendering, there is no control over document style

 Which is a good thing for accessibility reasons.  --Sparks 22:59, 3 December 2009 (UTC)

1. Yelp does not produce document indices when requested
2. Yelp can be slow. For larger documents, very slow. Breaking the document into multiple files does not help.
3. Yelp does not display the Publican-produced revision history
4. Publican cannot currently package multiple languages, and at this time, it appears it will not address yelp packaging in the future.

 Isn't this a disadvantage of using Publican?  --Sparks 22:59, 3 December 2009 (UTC)

1. Yelp addresses only Gnome and does not help other desktops
2. All languages are installed, whether or not needed. The installed size in all languages for our longer documents is hundreds of megabytes.
3. 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.

 In Fedora the package maintainer manages the package no matter if it is broken down by language or not.  --Sparks 22:59, 3 December 2009 (UTC)

1. 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.

Possible Improvements to Yelp

shaunm has suggested a meeting in 2010 of yelp stakeholders to discuss potential improvements to yelp. Some things that might be discussed:

1. Integrate with khelpcenter and other desktops
2. Repair limitations/bugs

Publican Packaging

Publican has the capability of building an rpm for its documents.

Characteristics of Publican

The Publican package produces an html document which is installed in an appropriate place on the fillesystem. A "Documentation" menu is added to the System menu with an entry for the document.

Requirements for Publican

No special requirements. Everything is handled automatically.

Advantages

1. Easy for Docs
2. Easy for translators to manage their own languages and push timely updates.
3. User views document in his preferred browser
4. With some manual work or an improvement to Publican, could also address KDE
5. Only the needed language(s) must be installed
6. Stand-alone documentation is separated from application Help
7. L10N teams can take ownership of packages in their languages, allowing them to issue updates and corrections without waiting for other teams and without overwhelming the maintainer of a single, large package.

Disadvantages

1. Document is separated from Help
2. User must install every desired language individually
3. User must manually select desired language from a potentially very long menu. Since only the title is available, and titles for some languages are identical, the user may need to open multiple documents to identify the appropriate one.
4. It is a change from the previous user experience

 Documents where included in a documentation menu previously, I'm not sure how this changes things other than using a browser instead of yelp. Tsagadai 00:00, 7 December 2009 (UTC)

1. Requires translators to manage many packages for their language.

 This could be automated by Flies or Transifix. Tsagadai 00:00, 7 December 2009 (UTC)

Publican multi-Language Suggestion

Jeff Fearn suggested using Javascript to allow automatic language selection of html documents.

Characteristics of Publican MLS

User sees a "Documentatation" submenu as in the Publican-packaged approach, but there is only a single entry per document. On selecting a document, the user is presented with the document in his preferred browser and the appropriate language.

Requirements for Publican MLS

1. Document is in html, Publican html is perfectly adequate
2. Document is manually packaged as for Yelp ( Example .spec file )
3. A hand-crafted index file is provided to select the language. See Example index for an example.
4. A hand-crafted .desktop file is provided to create the menu entry. See Example .desktop for an example. A separate, almost identical, file is required for KDE.

Advantages

1. User sees document in his preferred browser in the selected logon language
2. Applicable to both Gnome and KDE

Disadvantages

1. Manual packaging required
2. Documents are separate from help so potentially harder to find
3. Javascript can be cranky across browsers
4. All languages are installed, whether or not needed
5. It is a change from the previous user experience