Documentation/Help Content Modernization

TDF LibreOffice Document Liberation Project Community Blogs Weblate Nextcloud Redmine Ask LibreOffice Donate

• Wiki Home
• Development
• Design
• QA
• Events
• Documentation
• Website
• Localization
• Accessibility
• Marketing
• Diversity
• Wiki Help

• Documentation Home
• Official Publications
• Other Resources
• FAQ
• HowTo
• Macros
• Docs Development

Introduction

Since the birth of OpenOffice.org, the help content has relied in a set of tools developed internally. In particular, the display of the help pages is done by a XSLT transform of XML files in Wrter/Web with very few graphic, multimedia and rendering resources and standardizes in HTML 3.2, according to this source

The objective of this project is to replace the local help application into a modern browser with the 2016's web technology. The advantages are many:

1. Use modern system's browser to display the help content.
2. Add modern resources such as multimedia, MathML, SVG, GIFs into the local help content for better user experience.
3. Build bridges to make the help content available to on-line servers, with the same capabilities of the local help.
4. Ease the access of the community in contributing to help content.

The execution of this project can be through bugzilla tasks connected to one main bugzilla metabug. Each task can be transformed into an GSOC project, or in many cases, as easy hacks.

Preserve translation

Whatever technology is used, the contents and its translations of the current help system must be preserved. This is a sine qua non condition

Display in local system browser

This task will make the help content display in a modern browser such as MS Edge, Firefox, Google or Safari and their associated derivatives. Once the help button is pressed, LibreOffice will call the browser passing an URL with the file or service necessary to display the current help content. The current help content is in XML files. These XMLs will be transformed into HTML or HTML5, with the necessary enhanced CSS to be rendered in the browser either in a new window or in a new tab. The navigation of the help content shall be initially the same as the primitive internal browser.

Search text in help

To be addressed

Some ideas in Regina Henschel dashboard: https://wiki.documentfoundation.org/User:Regina/HelpAuthoringDashboard#Future:_TOC_and_Index

Build / packaging strategy

Transform all XHP help pages in HTML(5) at build time and pass the help URL to the local browser. Use the (new) local help content in the browser if installed, use the online help if not.

On-line help content

Contains the XHP help files transformed in HTML:

http://helponline.libreoffice.org

Some interesting properties of transformed pages in a modern browser (Firefox, Chrome, Safari, MS Edge, Opera):

• Responsive layouts (can be opened in mobiles and tablets)
• Use of browser navigation buttons for backward and forward navigation (done).
• Use of the cascading style sheet for improved user experience.
• Use the internal browser search mechanism to locate a string in the page and in the index.
• Use browser bookmark mechanism for page bookmarking
• Debug area indicating the XHP source page.
• Pages displayed are the release branch indicated in the header
• Index is per module and common features (SHARED help pages)

Multimedia and rich content tdf#97628

Since the display will be in a modern browser, this task will lay out the infrastructure for adding rich content to the XHP help files. The list below is a non exhausting set of to-dos

1. Create a multimedia folder in helpcontent2/ git sub-project, with name multimedia/
2. In the multimedia/ folder, create L10n folders (because multimedia may need localization)
3. Define a fall-back L10N folder.
4. Adjust existing Makefiles for builds.
5. Multimedia content will be packed inside language help packs.
6. Handle display of the icon set.

Rich content

• Videos (standard set of open standards video technology), screencasts.
• Images (PNG, JPEG, GIF, SVG, etc...).
• MathML (Calc functions, Math examples, etc…)
• Example files: In some cases a link to a ODF file with the example is more effective that a full textual description of the subject. For example, some Calc functions pages could open a Calc spreadsheet with the example inside.
• Other rich resources compatible with modern browsers

CSS for branding

This easy hack will enhance or define new CSS entries to achieve a visual effect that is aligned with TDF branding of LibreOffice or to other LibreOffice derived products.

Note: the CSS for the internal browser is set according to L10N.

Adjust HelpAuthoring tool

In order to deal with the new rich features, the HelpAuthoring too will need to be touched as well, but is a later phase.

Issues to watch

The project shall not touch help page contents, unless absolutely necessary. All changes in help page contents (XHP files) shall preserve the settings of the translation workflow, preventing rework of strings translation (fuzzy state).

What this project is NOT

The project does not deal with the content of the help pages.

The project does not handle the Help Authoring tool. Regina Henschel has a lot of good ideas on the Help Authoring tool: https://wiki.documentfoundation.org/User:Regina/HelpAuthoringDashboard

Related information

Links in the bottom of Regina's page are very useful to rescue history of the help content.