Taming LibreOffice 6.1’s New Help System

or… the Help must help.

LibreOffice 6.1 has been released and carries a refactored and improved new Help system, based on modern browser technologies. Let’s explore what this new help brought to LibreOffice.

The main driver of the new Help is our vision that the Help must help. When we look at the old help system from the perspective of a typical user, we realize quickly that the text and layout of the help pages don’t provide the best experience. So how can we improve the experience and help our users better? The diagnostic was straightforward: the LibreOffice Help system was tied to a very limited technology, so we had to unleash LibreOffice Help.

The approach was to look at the capabilities of modern browser technologies of 2018, and compare them to the aging help system that relied on 2000’s web standards. Until LibreOffice 6.1, the local help consisted of static description text, very few images, no multimedia and almost no easy support for evolution and improvements.

We had to preserve the legacy XML Help contents, evolve smoothly and redo the Help module to benefit from the latest browser technologies. Here are some of the results of this approach:

• We improved the page rendering, using JavaScript and Cascading Style Sheets (CSS) for a better user experience, which includes perfect display in tablets and mobile phones as well.
• We use the navigation, zooming, and bookmarking features existing in any browser.
• Using just one transformation for the local and online versions of the New Help, we have the same page layout for the two ways of accessing the Help.
• We preserved the localization (l10n) process in place, meaning that the new Help changes are transparent for translators.
• The old help module, coded in C++ and using Writer’s Web module, is no longer necessary and will be surgically discarded from the main code in the near future.

What’s new in the New Help?

Besides the benefits mentioned above, the new help is now capable of many new features.

Multimedia

We have enabled the possibility to include multimedia (videos and audio) in the help pages. Although this is deployed only in the online version of the new Help, multimedia is one of these resources that can turn a textual descriptions into pleasant short videos explaining the contents. Multimedia is a domain to explore and turn the Help into a richer experience, but it nevertheless requires skills for proper content production and must address our localization requirements.

Take a look of this sample multimedia and feel how it can improve user experience in our help pages: https://help.libreoffice.org/6.1/en-US/text/scalc/main0000.html

Collateral files

Another resource we implemented, together with multimedia, is the possibility to download collateral files. A collateral file is a companion file available in the help page that contains examples of the page’s subject. For example, we have a collateral file for Calc’s pivot tables and pivot charts. The collateral file is designed to be simple and effective, and can be used as a starting point for a larger project and to exercise the concepts developed in the help page. As the reader can imagine, creating collateral files for all subjects available in the help page is a challenge, and support from the community is necessary.

JavaScript and CSS

More enhancements are now inside the help pages using JavaScript and CSS. Calc function examples and Math examples can now be copied to the clipboard and pasted into the actual document. Just click on the example content to copy it to the clipboard. A tooltip also indicates the contents to copy. In both cases, the idea is to close the gap between textual descriptions and living examples. making the help more effective.

The right usage of JS and CSS also brought us the display of our online help pages in tablets and mobile phones. At the right time in near future, a LibreOffice Online user will also benefit of the online Help improvements.

Known issues

The new Help system does not have a global search function for the local help. That is, there is no way to search for a keyword in all pages. Part of the need for search can be provided by the index search if the keyword was bookmarked in the source file. In the online version, we temporary used a known search engine to supply a customized search mechanism, and we plan to implement a more effective, controllable and effective engine.

Also, the new help system has not approached the help pages of LibreOffice extensions. This limitation will be addressed later, as time permits.

The road ahead

The current new Help is just the beginning. Let’s free our imagination and implement or improve our help resources. Along with creating more multimedia and more collateral files, creating more screenshots of dialogs in our help pages. Some new projects are in the pipeline, notably the Help editor and a new display of the icons.

Editing XML files is not a fun task, it requires knowledge of the specifics of the Help XML and developer knowledge to submit changes to our version control. To make it easy, we are working on an online XML editor to accelerate content creation for the Help, The editor will have code snippets to ease the editing work, such as – technically speaking – generation of the unique IDs of each paragraph in the current page, a very cumbersome task for the content editor.

The new Help uses the Colibre icon set developed by A. Kainz. At the moment we used the PNG file format for a quick implementation, but Colibre icons source files are in SVG format, which allows perfect resizing.

Say tuned for the release of the new help features and resources. Or give us a hand and help the documentation team today – it’s a great way to build up experience in a well-known open source project, possibly for a future career in technical writing!

Aknowledgments

Some community members played a key role in the development of the New Help. We are grateful to them, and in special to

Ilmari Lauhakangas and Adolfo Jayme Barrientos for their contributions to the styling (CSS) and javascript code for page rendering in all device form factors

Andrea Kainz for the new set of Colibre icons.

David Tardon and Stephan Bergman for their incredible work in adding the New Help in the gbuild process and packaging.

Mike Saunders for his work on the Help editor.

Jan Holesovsky for his continuous support and advise.

The Document Foundation staff members for keeping the engine running.