We're sorry but this page doesn't work properly without JavaScript enabled. Please enable it to continue.
Feedback

Getting to Closer to a Software Help Language

00:00

Formal Metadata

Title
Getting to Closer to a Software Help Language
Subtitle
Untangling complexities of the LibreOffice Help
Title of Series
Number of Parts
561
Author
License
CC Attribution 2.0 Belgium:
You are free to use, adapt and copy, distribute and transmit the work or content in adapted or unchanged form for any legal purpose as long as the work is attributed to the author in the manner specified by the author or licensor.
Identifiers
Publisher
Release Date
Language

Content Metadata

Subject Area
Genre
Abstract
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.
10
58
80
111
137
Thumbnail
15:21
159
Thumbnail
18:51
168
Thumbnail
26:18
213
221
Thumbnail
15:22
234
Thumbnail
49:51
248
Thumbnail
23:06
256
268
283
Thumbnail
28:38
313
Thumbnail
1:00:10
318
Thumbnail
21:35
343
345
Thumbnail
36:13
353
Thumbnail
18:44
369
370
373
Thumbnail
44:37
396
Thumbnail
28:21
413
Thumbnail
16:24
439
455
Thumbnail
25:10
529
Thumbnail
15:36
535
Thumbnail
28:04
552
SoftwareProgramming languageSoftware developerOnline helpElement (mathematics)Web pageFocus (optics)Open setLatent heatModul <Datentyp>Computer-generated imageryMultimediaTranslation (relic)Process (computing)GUI widgetMenu (computing)Computer iconElectronic program guideSubject indexingNamespaceContent (media)Shape (magazine)Problemorientierte ProgrammierspracheCartesian coordinate systemMenu (computing)Web pageGUI widgetPresentation of a groupMoment (mathematics)MathematicsComputer iconMultiplication signOnline helpProgramming languageSpreadsheetNoise (electronics)Nichtlineares GleichungssystemMedical imagingCycle (graph theory)Transformation (genetics)User interfaceContent (media)Form (programming)MultimediaEnthalpyTranslation (relic)Subject indexingElectronic program guideCodeSoftware developerDegree (graph theory)Latent heatIntegrated development environmentRepresentation (politics)Address spaceElectric generatorOffice suiteModule (mathematics)NamespaceSoftwareTerm (mathematics)Descriptive statisticsTelecommunicationProcess (computing)SubsetDatabasePosition operatorFlow separationLinear regressionWordQuicksortSet (mathematics)Element (mathematics)Direction (geometry)Open setComputer animation
Computer iconNamespaceSystem programmingComputer-generated imageryContext awarenessBlock (periodic table)Physical systemCodeTable (information)Wage labourGUI widgetoutputMenu (computing)CollaborationismData conversionOpen setCartesian coordinate systemBlock (periodic table)Transformation (genetics)InformationComputer iconContent (media)Electronic visual displayTouchscreenMultiplication signText editorCodeKey (cryptography)Process (computing)Server (computing)Latent heatWeb pageCodeMedical imagingHome pageConstraint (mathematics)Projective planeSocial classSpreadsheetOnline helpTable (information)User interfaceElectronic program guidePhysical systemWindowPatch (Unix)Service (economics)outputKeyboard shortcutComputer fileMathematicsProgramming languageDifferent (Kate Ryan album)Context awarenessDescriptive statisticsSet (mathematics)Open setCycle (graph theory)Alpha (investment)ResultantLine (geometry)VolumenvisualisierungWell-formed formulaMereologyCollaborationism
NamespaceCollaborationismData conversionOpen setCartesian coordinate systemOpen sourceProgramming languageInformationComputer architectureOnline helpMachine visionOnline service providerContext awarenessOpen setStandard deviationType theoryMultiplication signSmoothingPresentation of a groupMusical ensembleContent (media)Translation (relic)Address spaceMoment (mathematics)Different (Kate Ryan album)Computer animation
Perfect groupTouchscreenOpen sourceOffice suiteOnline helpCorrespondence (mathematics)Decision theoryHome pageComputing platformOpen setMedical imagingComputer animation
Translation (relic)Online helpDecision theoryProgramming languageContent (media)WhiteboardMoment (mathematics)Different (Kate Ryan album)Projective planeBasis <Mathematik>Computer animation
Basis <Mathematik>TrailRight angleHand fanComputer animationMeeting/Interview
Computer animation
Transcript: English(auto-generated)
I'm going to talk about one of the challenges that we have in the domain of the LibreOffice, in terms of getting a help language that could help users and keep a lot of requirements
in maintaining documentation synchronized with the developments. My name is Olivier. I am from the Document Foundation. I have been involved in LibreOffice since the beginning. I live in Brazil, which is quite hot at the moment, 42 degrees.
And I'm also the translator for Brazilian Portuguese. So I handle not only the generation of documentation, but also the issue of translating the documentation. What we have is why we need a help language. Because historically the developers don't like to make documentations.
So essentially in our culture, in LibreOffice, everybody writes code but doesn't like to write documentation. So sometimes we have a lot of new features without documentation, and this is something that we need to fix.
The gap between the features and the help is widening. We are working to make it narrow possible, but it's always very hard. And the speed of development is much faster than the possibility of generating documentation, especially because in our environment, documentation is done by volunteers.
So coupling the help pages and the user interface elements is a challenge. The user interface of an application like LibreOffice is extremely extensive. We have more than 1,000 dialogues.
We have a span of application that goes from spreadsheets, text documents, presentations, drawing, math equations, and databases. So it's a very broad scope of application. And we try to focus on user experience, because user experience is very important for us,
for the acceptance of our software. So basically what we want to achieve is sort of a help language or XML, maybe XML or whatever, markdown, as open as possible.
Okay, so no way to use closed tools or paid tools or proprietary tools. Flexible, that allows specific situations such as translations. Has to be precise, because essentially the help that we have in LibreOffice is also
some form of a reference for regressions and feature descriptions. We would like, and this is one of the main issues, is to be contributor-friendly. Today it's not contributor-friendly, because we have a cycle of development that includes the help pages into Git, and this is not very easy for the newcomers.
And keep the pace of development, that means don't let this gap widen. Very well. So basically, the specifics of LibreOffice help, it's an application with a broad scope,
like I said. All the modules are tightly coupled. I mean, we don't have a spreadsheet application, we don't have a text document application. This is all integrated into a big application with several modules. We have a legacy XML, which is inherited from OpenOffice.
The help that we have at the moment is above 500,000 words, which makes a book as thick as this one. We have to maintain and keep alive.
It's mostly textual and few images. There is not multimedia at the moment, but the idea is to extend that for including new forms of communication between the help and the user.
And we have a translation process in place that works. That means LibreOffice is translated into about 100 languages. So we need to address the translation. We do that, which also means that it's very hard for us to change the process in place
because we are touching about 100 teams of translators. And when we do a mistake times 100, that makes a lot of noise. So this is the challenge that we have.
And what we do propose with us, with what we have, is that we have a set of XML and namespace that we want to improve for describing the menu path, the widgets, screenshots of the dialogues, describe icons and toolbars, includes multimedia, address the guide for
user and not only references, and also do indexing and search and save the translation work. At the moment, only half of these specifications are already working, and we have others to address.
For example, the menus in the application are described by an XML, and we would like to have these menu paths described in the textual help directly taken from the application.
So we should use a transformation that picks the XML of the menus and the commands and puts it into the help directly. So if we change the position of these menus, automatically your help will change as well. This is one of the challenges that we have.
The same for the widgets of the dialogues, for example. Not only do we have to take the widget itself, the representation of the widget, but also its contents, which has to be translated.
So again, we can use the dialogues XML, which is something used by GTK. The dialogues are in a GTK language. And to bring that into the helper pages. Icons and toolbars.
We have to describe the icons and toolbars for improvements on the icon designs. In the last couple of years, we had a lot of discussion in LibreOffice design team. There are quite new icons coming, icon sets. So the interface may appear different from you.
From one user to the other, depending on the set of icons that you use. This has to be also covered by the help application. The screenshots. We have already screenshots done by a simple copy of the screen in an automated process.
But it would be nice to have it also using the XML to generate the image. The images is already implemented, so no problem there. And also we have some issues or problems to address, which means
our system, our application runs on Mac, Windows, and Unix. And depending on the system, you have some features implemented on Mac, which is not implemented on Windows.
Very few of them, not that much. But nevertheless, we have to address this difference between the systems. We have also inline context switches or block contents switches.
For the visual part, we are implementing specific tags to describe Python code and basic codes, and also code in general, and icons specifically to icon tables.
When it comes to tips, notes, and warnings, this is already done. It's quite easy to just address the CSS. But it's the way that we have also to enhance the layout of all pages.
For everything like that, we also have character set, character classes for specific contents of the description on the helper pages, such as literal information. Input is something that allows us to click on a class input, and then it copies to the
clipboard, so if you have a code or a spreadsheet formula, you can just copy the formula and look at it working directly in the application. This is for better user experience.
Widgets, I already talked about. Menus and key codes also for all the keyboard codes that we have in the application. We developed also an online editor. This is the very first pre-alpha display.
We have the XML of our editor. Some of these blocks can be automated, and we also can render the content of the page immediately after we edit here. You edit here, you click on render, and it displays the page there.
Our help system is a sub-module in Git, so every time we change the XML, we have to create a commit and push to get it. It's going to be reviewed by someone.
You can imagine that reviewing XML is not something easy. It's quite complicated, so we are trying to connect this kind of editor, which this is just CodeMirror, a very well-known JavaScript editor.
It's the same as Gerrit, so we expect to be able to edit directly the pages in Gerrit and get the results and submit the patch automatically. We would like to avoid all the work that today volunteers have, which means download
the code, compile the code, compile the help, check if the change is correct, and then generate a patch and push to the... So this cycle is extremely lengthy, and it takes a lot of time for us.
For me, who is skilled, it takes at least one hour to generate all the stuff. Okay, then what's next? It is of interest to investigate the XML transformations for dialogues, menus, and
toolbars. We also would like to converge the help with these existing Open Document Guides, which is a project we call Convergence. We have guides that have been written by volunteers, for example, on Spreadsheet. The Spreadsheet Guide is a book with 400 pages, and we would like also that this kind of
information be available in the help system of our LibreOffice. We are open to suggestions and collaboration, and if you want to join us, please go ahead. We are eager to get you. One thing that is important to say is that our help system is either offline and online,
which means that today we have this XML, we do a transformation to HTML, and this HTML can be uploaded to a server, or it can be also deployed as a package for offline use,
and it's exactly the same layout. This is a constraint that we have, so it's not so easy just to generate a server service installation. You have to also pack the HTML into a package.
The other thing is that we have about 2,500 files per language, and it generates
about 500 megabytes of help content per language. It's a pretty heavy application that we have. The traffic that we have on our online service is about 60,000 visits a day of people
looking for help when they use the application. That's the context that we have and the challenge that we are addressing ahead. We cannot throw away our legacy content, so using a brand new tool like I have seen
here is very nice, but how can I address all this legacy, especially not only the translations?
It's about 100 translations, so it has to be something smooth for us if we have to get something different from that. At the moment, this is not our vision. We expect to simplify and get it easier for the people to really help us in documenting
the application. Okay, that's my presentation. If you have questions, please. We have time for questions. Yes?
Are you familiar with the DTAB project, the DTAB standard? No, no. Darwin information type architecture. It's an XML language for documentation. It's huge. There's a really big community. It stands for Darwin because it's adaptable, so you can take the standards that has all
of this that you're defining and make your own specialization, and then you would be able to use their tooling. They have an open source tool called the Open Toolkit that allows you to generate a bunch of things. It's mostly proprietary community, but it's an open standard. It would be super awesome to get an open source community into that.
I can introduce you. Yeah. Yes, we are using, of course, all the legacy from 15 years of... I mean, 20 years of open office and then LibreOffice.
And moving away, we really have to make a decision. And if something is easier, then I'm interested. It's not necessarily easier, but there's more tooling. Yeah, okay.
It's also XML, so there's a community, mostly proprietary vendors that are using an open standard together, and there's a lot of interest for open source tooling. So there would be much need in that one. Oh, perfect.
Actually, I have a question as well. When you generate the screenshots, you generate them per platform? And I think it does macro those tools properly? You can generate the screenshots on every platform. But you automate them? It's not yet automated. I mean, I do make screenshots in my builds, and it generated the screen starts to flicker
because it opens all the thousands dialogues and takes a screenshot. Then you have to connect the screenshot, the image,
with the dialogue and with the help page corresponding. This is not yet automated. Yes? Yes?
Well, no, the translation is done by volunteers in every language. We used to have a leader and a team, and they handle themselves.
I mean, each release that we have, and we have two release per year, we publish the help. 99% of the help of the new release is exactly the same of the previous.
So there is only the delta, the difference that is being addressed. And then the translators, the team of translators, the locally is in charge of keeping the translation synchronized with the help in English. Then the user of their language will suffer because they were not addressing.
Yeah, no, no. This is because this is a volunteer project. There is no specific investment by the foundation into generating professional documentation.
This is a decision with the board of the foundation.
LibreOffice is a project that is run by a foundation with no non-for-profits. If a company wants to take the code and improve it by themselves, they are free to do that.
At the moment, we generate the content of the help in a volunteer basis. The foundation doesn't invest in... Oh, this is not me. Okay, any questions?
Thank you very much. Yeah, thank you. Because he usually has his own track somewhere as well, doesn't he? Yeah, there is another track right there, yes, with lots of new things.
We'll be back again in about eight minutes with a smackdown. I'm a huge fan of Pandoc, and this next week he wants to tell me why I shouldn't be.