Desktop Documentation Presentation Options

This page is a draft only
It is still under construction and content may change. Do not rely on the information on this page.

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.

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. 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
2. Since yelp handles rendering, there is no control over document style
3. Yelp does not produce document indices when requested
4. Yelp can be slow. For larger documents, very slow. Breaking the document into multiple files does not help.
5. Yelp does not display the Publican-produced revision history
6. Publican cannot currently package multiple languages, and at this time, it appears it will not address yelp packaging in the future.
7. Yelp addresses only Gnome and does not help other desktops

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
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. User views document in his preferred browser
3. With some manual work or an improvement to Publican, could also address KDE

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

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
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 select the language. See Example .desktop for an example.

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. It is a change from the previous user experience