LibreOffice Community Week: Documentation

The LibreOffice project is made up of many communities working on different aspects of the software: source code, documentation, quality assurance, design and other matters. Some people are working full time, many others are volunteers, and we always try to make new contributors feel welcome.

So throughout October we’ll be running LibreOffice Community Weeks, looking at the different sub-projects in LibreOffice, what they do, and how to get involved. We start off this week by looking at the documentation project, and chat to Olivier Hallot, who is leading the effort to improve LibreOffice’s guide books and online help…

What is your role in the documentation project?

My role in the documentation project is to elaborate plans, coordinate and increase the collaboration of the community and improve the contents of the documentation of LibreOffice.

How did you get involved in LibreOffice?

I am involved in LibreOffice since its beginning, and even before during the OpenOffice.org times in 2001. In the last decade I had an active position in the Brazilian community as member of the BrOffice NGO, and also because I coordinated and translated OpenOffice.org’s User Interface and Help Content to Brazilian Portuguese, a task I carry on to date with LibreOffice. I also took job on OpenOffice.org migration consulting in very large companies in Brazil and later I participated in the creation of The Document Foundation (TDF) in 2010, being member of its Board of Directors from 2010 to early 2014.

Having an experience in the corporate arena, I was concerned that gap between the documentation and Help Content of LibreOffice with respect to its features was dangerously growing, and that has to be reverted so the software and its collateral documentation has to go ideally hand on hand. On presenting the issue in our LibOConf in Aarhus (Quo Vadis HelpContent?), TDF understood that it was necessary to take action and here I am.

What does your typical workday look like?

Since I live in Rio de Janeiro, Brazil, I must admit that when I wake up, people in Europe are already working full steam ahead and I have a feeling that I am always late and sleepy (laugh) in the job. Anyway, usually I check my mails just after my breakfast, and I get ready for the online meetings that for me are in the morning.

Then with the list of task from the meetings, which I cross-check with the off-line mails, I start at least one task to get it done in the day. That includes support in chats, answering e-mails in lists and off-list, and also updating a document, a wiki page or a web page.

You see, writing documentation on LibreOffice is a task that requires several hours or days of concentration and we must be focused all the time. To be able to write or review a specific feature, you must test the feature in your installation, understand the implication of the feature and even add some of your personal knowledge to give the reader a quality text and content.

How many people are involved in the doc project?

The doc project has two main lines: The literature and the Help content. The Help content is itself divided into contents and technology modernization.

On the literature, we are about three to five people contributing once in a while and this is an exposure. We need to update our books in timely fashion because they are considered as the official TDF books for LibreOffice and are translated into several languages. Since the license is Creative Commons, these books are also sources for other books on LibreOffice in many languages and communities.

On the help content, we have the valuable contribution of many individuals (from 10 to 20 persons), from translators to developers that help us to correct the contents and adjust the help pages to the new features and UI changes. The accuracy of the help pages is also an exposure we carry and our task is to close the gap. It must be noted that the correct description of a new feature is important for legacy purposes: if later on in the LibreOffice project, the feature does not work anymore, we still have a description of its existence and normal behavior.

Finally we consider that the current Help system, which is based on XML files transformed into HTML3.2 pages displayed as Writer/web documents can evolve to a modern browser-based technology. There are some tech issues yet to solve, especially because the Help system translation process is consolidated, works satisfactorily and its content must be preserved.

What’s been the biggest success so far, and the biggest challenge?

We updated the Getting Started Book to version 5.1 of LibreOffice, and we managed to put the help pages directly into a web server, at least as proof of concept, showing that we can evolve and achieve a better, richer help content.

My personal challenge is to produce the TDF LibreOffice Guides as a genuine companion product of the software, where the LibreOffice brand provides not only the software but also the collateral products for those migration or training professionals that support the deployment of LibreOffice in organizations.

I also pretend to close the distance between the user and the documentation. The usual way for the user is to hit F1 to get help but if the help is not enough, users go to Google and try a search for contents he is looking for. This is a time consuming task and we have already put entries in the software Help menu to link the software to the documentation website and to community forums. We expect an increase of visits to these services in benefit for our installed base.

But then the challenge is to get more contributors to help with documentation of LibreOffice, in all areas above. Authoring, reviewing and updating a book is a task that can be carried by non-developers, provided they have good knowledge in the software as advance user and have time do dedicate to the LibreOffice literature. The same is for the local communities if they want to translate LibreOffice books.

On the technology of the Help, the challenge is to select a viable technology to replace the current Help system.

What sort of help are you looking for?

We look for more contributors, people that can write, review, advanced contents on LibreOffice. It is important that we see the TDF LibeOffice Guides as a genuine companion product of the sofware, where TDF provides not only the software but also the collateral products for those professionals that support the deployment of LibreOffice in organizations.

Stay tuned to the blog for more about the documentation team this week – including a list of who’s who in the project, the tools being used, and how to get involved yourself! See here for more information on the docs team.