Getting to Closer to a Software Help Language
This is a modal window.
The media could not be loaded, either because the server or network failed or because the format is not supported.
Formal Metadata
| Title |
| |
| Subtitle |
| |
| 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 | 10.5446/44288 (DOI) | |
| Publisher | ||
| Release Date | ||
| Language |
Content Metadata
| Subject Area | ||
| Genre | ||
| Abstract |
|
FOSDEM 201941 / 561
1
9
10
15
18
19
23
24
27
29
31
33
34
35
38
39
40
43
47
49
52
53
54
55
58
59
60
63
65
67
69
70
78
80
82
87
93
95
97
102
103
104
107
110
111
114
116
118
120
122
123
126
127
131
133
136
137
139
141
142
148
153
155
157
159
163
164
168
169
170
171
172
173
174
181
183
185
187
188
193
196
197
198
199
200
201
205
207
208
209
211
213
214
218
221
223
224
226
230
232
234
235
236
244
248
250
251
252
253
255
256
257
262
263
264
268
269
271
274
275
276
278
280
281
283
284
288
289
290
293
294
296
297
300
301
304
309
311
312
313
314
315
317
318
321
322
327
332
333
334
335
336
337
338
339
340
343
345
346
352
353
355
356
357
359
360
362
369
370
373
374
375
376
377
378
383
384
387
388
389
390
391
393
394
395
396
406
408
409
412
413
414
415
419
420
425
426
431
432
433
434
435
436
438
439
440
441
445
446
447
448
453
455
457
459
466
467
471
473
474
475
476
479
480
484
485
486
489
491
492
496
499
500
502
505
507
508
512
515
517
518
529
531
533
534
535
536
539
540
546
550
551
552
553
554
555
557
558
559
560
561
00:00
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
07:19
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
14:33
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
16:35
Perfect groupTouchscreenOpen sourceOffice suiteOnline helpCorrespondence (mathematics)Decision theoryHome pageComputing platformOpen setMedical imagingComputer animation
18:41
Translation (relic)Online helpDecision theoryProgramming languageContent (media)WhiteboardMoment (mathematics)Different (Kate Ryan album)Projective planeBasis <Mathematik>Computer animation
20:46
Basis <Mathematik>TrailRight angleHand fanComputer animationMeeting/Interview
21:30
Computer animation
Transcript: English(auto-generated)
00:05
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
00:23
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.
00:42
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.
01:04
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.
01:21
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.
01:45
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.
02:00
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,
02:24
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.
02:42
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
03:01
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.
03:25
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,
03:43
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.
04:08
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.
04:23
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.
04:41
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
05:06
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.
05:21
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
05:45
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.
06:05
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.
06:22
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.
06:44
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.
07:00
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.
07:21
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.
07:42
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.
08:06
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
08:26
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.
08:43
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.
09:01
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.
09:23
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.
09:41
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
10:06
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.
10:22
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.
10:43
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.
11:06
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.
11:23
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.
11:43
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
12:04
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.
12:21
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
12:42
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
13:04
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,
13:26
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,
13:43
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.
14:04
The other thing is that we have about 2,500 files per language, and it generates
14:21
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
14:47
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
15:06
here is very nice, but how can I address all this legacy, especially not only the translations?
15:20
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
15:44
the application. Okay, that's my presentation. If you have questions, please. We have time for questions. Yes?
16:00
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
16:21
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.
16:45
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.
17:00
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.
17:23
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.
17:42
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
18:04
because it opens all the thousands dialogues and takes a screenshot. Then you have to connect the screenshot, the image,
18:22
with the dialogue and with the help page corresponding. This is not yet automated. Yes? Yes?
18:50
Well, no, the translation is done by volunteers in every language. We used to have a leader and a team, and they handle themselves.
19:07
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.
19:22
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.
19:48
Yeah, no, no. This is because this is a volunteer project. There is no specific investment by the foundation into generating professional documentation.
20:12
This is a decision with the board of the foundation.
20:23
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.
20:42
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?
21:04
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.
21:20
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.