Olivier Hallot

LibreOffice has currently an large set of help pages which are hard to maintain and to edit. On the other hand the XML language used was designed for a broader purpose and is not used in its full capacity. The lecture presents simplifications of the help XML and the design of specific XML objects to describe the user interface and to connect the help pages closer to the dialogs of the application.

Software user interfaces has menus, toolbars, panes, dialogs, mouse clicks ad even voice to enable complex tasks for the user. Because of the cost of the screen real-estate, elements of interaction are concise either in textual form or in pictorial form (icons). The need of Help pages are necessary to give more details on the elements functionalities. But since the set of UI elements is limited in size, the elements of the Help pages should also be limited, and the corresponding help page element to UI element should be connected.

The lecture presents simplifications of the help XML and the design of specific XML objects to describe the user interface, to connect the help pages closer to the dialogs of the application and produce Help contents in a faster way, making easier to upgrade and to address softwares translations processes.

LibreOffice like other office suites, is a sophisticated, ubiquitous and complex end-user application, that demands good documentation to continue its strive. The current situation for LibreOffice documentation is that producing contents is still a lenghty and hard task, often requiring rework depending on different sort of publiccation needed. In this presentation, we will summarize the efforts done so far within the LibreOffice ecosystem and make the point on the need for a different approach to make the LibreOffice documentation an element of communty gathering and contribution, extending the range of the quality of the software.

Complex softwares for end-users like office suites or desktop environment, to name a few, are impacted in their adoption because of the need to educate and train users to the new tools. Undocumented software raise a set of issues that prevents broad adoption by the organizations or governments, and leave brilliant ideas and features into obscrurity. The Document Foundation and it's flagship software LibreOffice, as well as other FOSS communities needs to address the issue of making the end-user documetnation broadly available and updated.

On the other hand, end users being part of the software community, are often eager to collaborate and contribute to the software documentation, but hit a quite steep entry barrier because of the development skills need in editing software help files or on advanced word processing skills for editing a guide with the software. Also, Q&A-shaped web services, wikis and dynamic multimedia documentation also bring challenges to documentation because of the need for accuracy and update.

The purpose of the presentation is to deliver a vision on the optimal documentation production for complex end-user softwares, that will address several documentation issues existing in the FOSS business and community envoronment. We call this Project Convergence. Here is waht we foresee:

• Address the reduction of documentation rework, issues by the multiple publishing medias, such as online reading, printed guides or multimedia documents
• Have its contents editable by a large set of contributors, under proper security, and with the easiest way to add contents, so new contributors can quickly add contents instead of learning obscure features of the file markup.
• Be computer-aided-translation (CAT) friendly, to reach the broader public around the world in whatever language.
• Synchronized with the latest developments of the software, thus reducing the gap between development and documentation.

We will also present our latest development in the documentation tools of LibreOffice, in the effort to evolve technologically and benefit of the develpment of the web and invite for discussion all documentation leaders of similar software projects.

Currently the LibreOffice help system is based on a technology developed circa 2005, and uses the internal Writer - Web module to display its contents. This presentation introduces our efforts to bring the LibreOffice Help system into a modern 2017 technology, preserving our legacy contents and l10n processes.

Introduction

Currently the LibreOffice help system, here forth called HC2 is based on a technology developed circa 20051, and uses the internal Writer - Web module to display its contents. HC2 uses a combination of XML and XLST technology to display contents in Writer/Web and is historically bounded to HTML version 3.2 . As a consequence, the HC2 misses multimedia resources such as videos, animations as well as a modernized concept of CSS and Javascript for better user experience.

Further, the HC2 XML schema (XHP) requires special tools (HelpAuthoring) for editing its contents and a simple inspection on the schema indicates most of its elements are now part of W3C standard HTML5, turning XHP almost obsolete. Current help authoring tools are buggy and requires steep learning curve for the unskilled volunteers.

History of LibreOffice XML Help

LibreOffice Help System was designed and implemented in 2005 by SUN Microsystems ant the times where the "Browswer war" raged and no standard published by W3c was adopted in full by the major browser players. The WWW hijack by major corporations was played in the browser battlefield, twisting specs and invalidating page rendering to build fences around browsers and servers and creating silos of web display technologies;

SUN Microsystem adopted an internal only solution, with a A specific XML (XHP) to hold contents and navigation and an internal browser (Writer Web), that beared a resticted HTML 3.2 specification, together with a C++ wrapper to create index and proper calls

2017 issues for Help System

The current (2005) help system is in a state that is is complex edit/update contents, hard to test and visualize results. There is no rich text available except an authoring extension to LibreOffice that uses Writer as rich text editor but has several issues in exportng and importing xhp files. To use this extension features is as hard as learning XHP itself and as hard as to attempt to edit content with a simple text editor as vim or emacs.

Furthemore the rich text authoring is bounded to the current XHP schema, doubling the effort when it comed to evolove XHP, because the tools must follow the new schema.

The current HTML 3.2 implemetation with LibreOffice Writer / Web rendereing engine, is also bounded to simple images and text, and no video nor another multimedia resource is avalable for the user.

General requirements

The new help system for LibreOffice must support important requirements

It must preserve legacy contents, composed into thousands of XHP files covering all 6 LibreOffice modules and an internal user guide.

It must also preserve the dozens of translations done on these legacy XHP files and the translation process must be ideally preserved or incur in the least perturbation possible.

It must use open, royalty free standars of web technologies, supoort all major browsers of 2017, OS independent.

It must be of easy access, low entry barrier for newbies, volunteers an have support of ease of use editing tools.

It must be perfectly handled by git version control

It must work Off-line and on-line

Strategy

The strategy of the project is in 2 pieces

1) Progressively phase out XHP and phase-in HTML5

HTML5 is a serious candidate to deserve our efforts to bring back our hep content into a general purpose rendering technology, suport moder CSS, javascript, other companion technologies

2) Develop a micro javascript server capable of

• Display the correct help page required by the LibreOffce applicaiton
• Use most of the resources such as navigation history, bookmarking, caching incluced in any major browser
• Handle indexing and searching text among pages
• support XHP and HTML simultaneously

Demo

We will demo where we are at the moment

Concusions

Part of the cost of a technology adoption is its capability to be quickly absorbed by its target audiences. Documentation and help systems plays a key role for the adoption of LibreOffice not only in the home but also in the corporations. Having a dynamic and rich help content that can make users feel the better experience in seeking help is a key step LibreOffice project is taking to inclrease its popularity. The project described here is our current status and will be real very soon.