 Hello. Good afternoon. My name is Olivier. I am currently the documentation coordinator for TDF. And the idea I have here is to present to you the issues that we have in documentation and also get from you some feedback about where should we go in terms of documentation. Everybody knows what is this small application that we have in the cell phone? Do you know that we can control the presentation with the cell phone? But there is no help page for that. If you look into the help, you won't see any reference to impress remote. So this is one of the issues that we have. We have very nice features nobody knows about because there is no help. So this is one of the situation I have and I want to discuss with you because this is not something that requires rocket science to do. So it's a very low barrier entry for contributing to the project. And this is a nice feature that we have in this sense. Our documentation problem has three parts, three dimensions. When I started looking into the documentation more deeply, I found that you have a literature that is written by a group of authors. We have the issue on the help content that goes with the software that you download and also you have a copy of the help content in a Wiki page in a specific address, helplibreoffice.org. This Wiki is a copy of the help content. The third part is the community services. What TDF is doing to help users with the application? Well, please feel free to raise your hand and open for discussion. I am just using a presentation to give ideas and to address the issues that we have. Very well. Let's talk then about the books. We have a set of books that were written in the time of OpenOffice and were transported, brought to LibreOffice. This project was driven by Jean Weber, an Australian lady that was a professional technical writer, and she brought to us all her experience on writing technical books. She is extremely skilled for that. This is, let's say, quoting her baby. It's a very interesting activity that she did for us. What we have at the moment is a getting started book that we are almost ready to upgrade to the latest release of LibreOffice 5.2. We just finished 5.1 and the amount of work to update to 5.2 is very small, very small. We have the writer guide that is in release 4. Jean today is working to upgrade it to 5. And we have the calc guide that is also late in release 4. And then we have the other guides that are even more lagging in terms of time. Getting started guide, like I said, is very easy. The other ones need a better understanding of the application. So if you want to write and update these books, then you have to really understand the application, understand the module, for example, the spreadsheet, and be able to really add value to the content of the book. Not only by updating with the new developments done by the software, but also maybe bringing to the book your experience on being a consultant or being a professional user of the application. If you work in accounting companies and you want to write about the spreadsheet, then your experience may be interesting for us and for the community. Very well. Questions? Questions? Yes, go. Yeah, then you have Super Milosh, who has all the procedures to use a computer-aided translator to Omega T. That makes it extremely fast to translate. Milosh may want to speak about that. You have done all the procedures you have explained. I have used your procedure for the Brazilians. We are at the moment only finishing the revision of the translation, and I can tell you once we finish 5.0, which is already at the moment, and we go to 5.2, it will be in a snapshot to update the translation. So this issue is we have a solution. Milosh knows it. Another language community. We are actually sitting here. We translate it not from English to Slovak and English to Czech, but we use Google Translate in English to languages, and in our case it gives 90% good text. This workshop also helps you to know who is really skilled and could give you a good start. I would also say that if you know what is PUTL, Omega T is also a computer-aided translator with memory. So the fact that you have an updated sentence, it will offer you several possibilities of translation. In summary, it will speed up very well the work of translation. So this is the situation of the books. And like I said, it needs dedication for someone that is knowledgeable in the context to really write a good text. And also what is important is that this set of books is also used as a reference for other communities. People like to get these books as the official TDF books and then start translated into their language. Also, these books are interesting to be a source of an independent literature about library office. Since we have a Creative Commons license, you may use the contents to produce another content of your authorship. So this is another contribution that we have from TDF for the community. Well, books are important. Like I said, it's used as reference for other books. It's a reference for the translators. And also it's appointed like appointed by TDF and considered an official documentation for library office. And what is important? Because you can just download the software. But then if you want to invest into the software of your personal time, you will hit very soon the need of finding documentation. To find experience on the software written by other people. To increase your knowledge of the software. And this cannot be done exactly. It's not very effective for trial and error. Sometimes you want to shortcut and go directly to the contents that helps you in doing your task. Very well. So what is the workflow for updating the books? It's not difficult. We first have to go to the ODF author website. It's a website that is hosted inside TDF infrastructure. It's a prone site and it's used to store our books. Then if you ask us the permission for an account, and then when you go there, you pick one of the chapters that is already published and you download the source. It is an ODT file. That is it's a writer file. And you just read at it and you will see if you need to improve the contents or not. Sometimes you just don't need to touch anything. For example, between one release and another, the chapter that talks about ODF is not going to change. Almost nothing. It's a very easy task to just update the file and to put into this workflow. So you pick the number, the chapter of the previous release. You send to the documentation list that you will update the chapter so nobody does duplicated work. And then you enable the track changes. This is important because you will help the person that we revise to go directly into your changes. And then you do your tweaks. You do your updates. You have to respect the styling guides. I mean, you use the right styles for headings, paragraphs, captions. And notes, tips that we have in the book. The book is totally structured into styles. It has the best practice in terms of using styles in the text. So please respect this. Don't use direct formatting because this is going to have an impact in the omega t tool or the translation tool. So better use styles. And then you have to update the graphics and the screenshots if the screenshot has some changes. And then you upload your file into the draft folder that someone else is going to pick your file and do the revision and prepare for publication. So that's it, basically quite a simple workflow that allows us to really push the release faster. To avoid the situation that you have raised, that is, we are in release five and I have a book that is in release four because that gap takes time to fill. So if we can keep the development of the software close to the documentation, this gap is slow and makes us more effective. Okay, questions? Yes, the base guide. Yes, that's a good question. I have discussed it with Jean Weber and she said to me that we are late in the base guide and she told me that it seems that there is a German book that is much more complete and she asked if it can be translated to English. So in that case, the localized book to be translated in English would be a nice thing that we can do. Yes. Yeah. So the issue is not only translation but also redesign with the styling, the correct styling. Is that right? Okay. Yes. Whoever has translated the help, see when you have several tags in the middle of the text, it starts to be very cumbersome to translate. So... Yeah. Yeah. I think it should be done. It should be done. What can we do then next? We can match the German and English translation, the original and the English translation, build the... Memory. Yeah. You have everything in the translation. Yes, so you have the... Do you have a translation memory for Kau? Or are we not? Because we just have a special interview about translation and some control of things. And this would be a great help in many concerns. You have rabbit translation memory. Yeah. German translation. We have some of that. If you have the original and the translation, there is a tool, a script, that can build the translation memory. It's very difficult. Okay, good. You say if there is a script, where can we find it? Because in Dutch we will have quite a lot of translated chapters. Yes. I think that the script for alignment is done by Miloch, no? No, no. Aligner, yes. Yeah. And Miloch also wrote a page on the wiki with almost the same contents of your presentation with the details on how to build a group of translators using Omega T. Sophie, okay. I translated your page in Brazilian Portuguese and we used the information for this purpose. I give you the links. So basically we take a chapter of the previous release. We update it by reading carefully and see if there is anything that is new. We update the text and then we submit for revision. Okay, not forgetting to enable the track changes because the track changes really will give you a visual indication of the modifications. Okay, very well. Some hints and tips of the books. I have perhaps already said that. The Getting Started is an introductory text so there is no need to go into very deep details. Okay, it's a book for newbies, people that are just starting in the library office so that function that calculates the ledger of one investment is not the right contents for an introductory book. Okay, if we need more attention then we go to the guides of each application. Then there we can specify things more complex. Okay, so it's sort of an easy hack for documentation to update these books on the library office. It's really very easy. It's so easy that I just wanted to do myself but I think it's not fair. I mean, the community should participate as well. Okay. Okay, any questions on books? Before we... Yes? Well, if you have the columns and the fields names in German it may be interesting to have an English because it helps us... Okay. Yes, in that case I think it will be interesting to translate the database. The queries. Well, yeah, you have a point. You have a point. It may... If it goes to... I mean, you translated from English to Dutch? Yeah, if the Dutch reader is comfortable with an English name, okay. I can tell you a Brazilian will not like to have a German name. It's impossible for him to understand. Okay, so in that case perhaps we have to consider if keeping the original example makes sense or not. Okay, for the variables. Well, okay, so any other questions on the books? No? Yes, please. Macros. Yeah, for the macros... Yeah, for the macros I think and maybe it's not the opinion of all of you but there is a book by an American author named Andrew Pitonjak. This is the best reference I have on macros. His book was published a couple of... I mean, 10 years ago, has been updated and his book is continuously being updated by himself and it's extremely complete book and it's available for downloads. I'm sorry, there is... It's available from downloads either in PDF and in ODT. So you can pick his book, give him your permission for translation and you can translate his book. Combine. The book by Andrew Pitonjak is... The title is perhaps but the application and the application program interface and the objects. Okay, yeah, I should have put perhaps his book as a reference for macros because it definitely is the best book I saw so far. It really helps for the one that has to migrate a macro in Excel to LibreOffice. It explains the API. It's really a very, very well documented book and he's very knowledgeable. Okay. All right, let's switch to the help content. Can we go? Okay, so the help content is a totally different issue that we have in documentation because the help content is embedded into the application. It is closely coupled with the application so when you hit F1 or when you press your help button then you will open the help contents. If the help content is installed in your machine it will open locally. Otherwise, Kendi has made a way to link the websites of the help to the application. Well, what is the issues of the help application today? First of all, it's a 2006 technology and no one has touched it since then. So it's 10 years, okay? When you press F1 and you see the help you will see, actually, you see a writer slash web displaying an HTML page. So the help content was designed to be a XML style sheet transformation to take XHHP files and display HTML. And since 2006, nobody touched this technology. Why did they, we don't touch? First of all, because for historical reasons developers don't like too much to write help pages, okay? The second one is that it is closely tied to translation process that we use. So the legacy that we have are the help files in XML. We call that XHP. And this, we cannot touch too much on these files without disturbing all the translation process. Okay? So it uses writer web as display engine. It's HHP files. And then when you see the help, you see one page that is the web page with the contents that you read. And on the left, you see an index that is built on by the compiler of the library or when you build the application. So the XML files are sourced for not only display the content but also an index. And this turns to be a little bit complicated if you want to touch it, okay? Well, what are the tools that we have for inserting help content? What can we do for you to help you to write a help page? I have three procedures, okay? One is if you don't want to go into the details of XML you can just write a page for me. You send to me and I transform it into a help page. I just want to show you basically what is the content that you should write. You, for example, in a blank page in writer, please, if you want to speak about the feature, for example, this impress remote. So the title is the impress remote, okay? Setting up impress remote. And then you have a short description. This feature does this and that, this and that, okay? Short description, one sentence or two, okay? And then you have a section where you say to access this function. How do I enable this function? And then you describe or you activate in the menu, you click that button or you activate that icon, okay? So you describe what is function, how to do this function. And then you give us a little bit more details on the function. The impress remote allows you to control your presentation with your cell phone in Android or iOS and blah, blah, blah, blah, blah. You make a short description, maybe one or two paragraphs, okay? Well, and then if you need parameters, then you start describing how to set up the parameters and where they are used and why they are used, okay? So you have parameters, parameters and such and such, okay? Then examples, okay? How to, if you have examples, not for this case here, but if you have a function on calc, you may want to throw some numbers and get some results, okay? Then tips and warning, what to do, what not to do, what is the best way to achieve some results, okay? And the last topic is a section where you see related topics. For example, if you were describing a mathematical function, you may want to refer to Wikipedia, okay? So you give a short description for the user, but if the user wants more information, go to Wikipedia or go to some other source of information, right? Is that difficult? No? Okay, so basically if you are able to write one page or one page and a half about that, then you can send it to me because I will take the contents and transform into a help file for a library office, right? Okay, this is the easy part. If you want to go further and be more hacky, then you can use the help-authoring extension. Have you heard about this extension? Yeah, okay. This extension was designed ten years ago by the guy that made the original help contents. It's a set of macros bundled into an extension that gives you a set of new commands in your writer application and then you can generate the help page almost automatically. I say almost automatically because this extension still has some glitches that prevents a full utilization of the extension. You will end up needing to look at the XML at the end, okay? But it's important, it's good for bulk insertion of text and some formatting, okay? Some formatting. Well, how do I use this extension? We can get it from the DevToolsLiberals.org which is a repository of tools for developers, okay? You just install the extension on a stable release of LibreOffice, possibly your personal copy, okay? Then you create and edit an existing help file, okay? And then when you are done, you save and submit to Garrett. All these things on editing file and submit for Garrett is something that requires skills on building LibreOffice. This may not be the case for everybody, okay? Because even with all the progress we did, it's not so easy to make it, okay? Well, what is the advantage of this extension is that you use a known tool which is Writer for addition and it's good for bulk insertions, I mean, for creation of the text, your content, okay? So if you have several paragraphs to put in your text, this is a good way to do it because you're using Writer. So if you want to copy and paste, it will be easy with this extension, okay? And you have to use some styles. I can show to you later on. I won't have time for that in this workshop. But if you want, I can show you how you use this extension for building the XML file, okay? So the point is it's good for some things, but it doesn't give you a complete file. You have to look at the XML at the end, okay? Well, the issues that I have, for example, in some files you cannot use copy, cut, and paste. There is a reason for that is that each paragraph in a help file has a unique identifier. This unique identifier is important because when we come to translation, it will be the unique identifier of the string in the help content. So if you change the ID of the paragraph, the translator will see there is a new string coming and he will discover that this new string is currently existing and was changed. So there is a reward to do, okay? So if you copy two paragraphs, you copy one paragraph and paste in the same file, you will have two paragraphs with the same ID, and this is going to break the build, okay? And it's not going to detect it for you, okay? And like I said already, when you are done with your file, you may need to edit the XHP file before submitting, okay? To fix, for example, the mistake that you did by copying and pasting a paragraph, okay? This is one example. I have others that are more cryptic. Questions, questions. No, no questions. Is it indicated? No? Very well. Then the third possibility is an experimental possibility thanks to Christian and the infra team. We have a virtual machine that is this one, vm173.documentation.org, and it has all the pages that we have in the help, okay? And inside that displays the help page live, I did it by tweaking the transformation to make it available for a browser, not only for Writer Web, but for a browser. It used to support a Christian make a link between PUTL and this site to help translators, okay? And it contains a simple editor for XHP files, okay? And the main drawback is that there is no checking on the XML schema, okay? I will show you, if you allow me, I will show you this, how it looks, okay? I have the page here. So this is basically what we have, an entry page, and if I click here, I am displaying, at the moment, the help page that we have when we start looking at the calc, okay? And then you can click on any link, and you will have the help page displayed in your browser. Okay, this is direct. This is direct XML file with the transformation. What it does is the Firefox downloads the XML files and also downloads the filter, and inside Firefox, inside the browser, it makes a transformation and does display this one, okay? On the left, there is a tentative and experiments to get all the bookmarks. It works more or less. It needs more work to be done on that, okay? I had no time so far. And also, if you notice, then on the top right, you will see what is the file that is displayed, okay? And the language and what the function, okay? So, information that helps people to see what is the content of the page in the help they are touching, okay? Any questions? Yes? Yes, for every page, I had to declare the style sheet to use and when Firefox downloads the XML files, it sees the style sheet and then it catches the style sheet to make the filter inside the browser and then generates XHTML here, okay? So, with this technology, it should be possible to enhance the content of the help file with other features such as multimedia, graphics, and other things that could be transformed to help page into something more comfortable to read, right? Also, all the links are working. And I also put into this virtual machine a small editor, a small PHP editor. I will show you how it works. It's very simple. If you want to do some quick testing on the rendering of your page, you can go and edit the XML file directly and refresh the page and it will show you what you did on your modification. For example, let me show you this small editor, okay? I have username and my password. Wrong password. So, basically, what you have is this is the help structure, okay? With you recognize Ascalc 00001. These are the folders where you have the XHP file and then on the middle here, you have one of the files open and it contains the XML that is the help file, okay? You can do editing right there. It's a simple text editing. It doesn't check anything, okay? So, if you made a mistake in the help, then you will run it through problems, okay? So, it's just for small adjustments or quick checking about an implementation you want to do, okay? Ideally, it could be a rich text editor tweaked to XML and it goes directly to the repository of the software, ideally, but I don't know yet how to do it, okay? But if you want to see specifically one of the files, this one is 05020301.XHP in your help repository, then you can have a quick display of it, right? Very well. Questions about that? You may want to know. So, it's another experiment. I call that an experiment because it's not yet finished and maybe in one of the meetings that we have in terms of engineering, our decision will be taken someday if we go this way or that way about the help. Yes? Questions? No? Well, let me just log out. In portal, let me give you an example. I will open portal here. If I take one of the files in portal, I want to translate it. For example, here is given a help page and on the left, you see here this link that will send you to the help page in VM 173. So, if you are caught into translating that data table in this file and you want to see what data table is talking about, then the page will be displayed if you click on this link, okay? So, here is the page. Here is the page where data table was to be translated. Okay? Who is translator here? Well, okay. I think that you understand the value of being able to access the context well on the text that you are translating. Okay? I am a translator too, so I know what I talk about. Very well. Very well. So, any question on this small addition that we did for you? No questions? Well, the other media. All the media that we made available for you, for the community, and it's involved the service that we have such as the wiki, okay? The wiki, they ask about the forums that we run, the mailing list, okay? And possibly also, we are considering the possibility of having a YouTube channel, I think it's already there, or maybe more dynamic videos and help assistant for the user. One thing I would like just to remind you, I made a comment in the translation list. We will have in 5.3 a new entry in the help menu. This new entry is get help online, right? And when you click on get help online, it will send you to a page of your community, for help of your community. For example, in the case of the Brazilians, it will go to the Portuguese ask about instance. Ask about is a question and answer site, and if the user wants to make questions for the community, this link will bring him directly to ask about. Instead of googling, it goes directly. Okay, so what will I need to complete this feature and set the infra team with the right links is that you tell us what page you want to open with this link. Okay, I think that the French wants to open a specific forum that is not under TDF control. The Brazilians and Portuguese are okay with TDF. The Germans too. Perhaps you want to tell us... Yeah. Search and ask about is quite easy, no? But if you want another link, just tell us that if you want to have a page that redirects you to several other links, it's also possible. It's just to shorten the access of the information service and the software. And not to go to Google and make questions, take several pages of Gribberish to find something that you really want. So you tell us if you want. And if you want to improve ask about, maybe, then within TDF we have a contract with the developer of ask about. He's providing us upgrades and bug fixes. So if there is some feature, maybe it would be interesting to see if we can implement it. The idea of ask about is similar of Stack Overflow. Stack Overflow is a very successful question and answer system. Okay. Gentlemen, ladies and gentlemen, any other questions? Any other discussion? What can we do? Please give us some feedback. Yeah. You have notes that user interface has changed and is changing quite frequently. So the menu entries are changing position and we have to update the help files explaining what are the new ways to access the same function. I saw really a lot of patches entering. I have a list, I will show you. I have a list of the missing features, the help page that we have. Let me just show it to you right now. Let me open here. It is, I have a meta, what we call a meta bug, which is a bug that has all the bugs independent and at least all the features that are missing. Let me just increase here so that we can... Okay. For example, write help page for Calc Stream. There is a function in Calc, named Calc Stream and nothing is explaining this function. Okay. I recently wrote the 8652 write help page for CMIS file access. I just did it a couple of weeks ago, which is the way that you open files in remote servers such as Alfresco, SharePoint and such. Okay. So many of the help page that are missing, so please be my guest to pick one of these bugs, write about it and send it to us. It will go to the help. Okay. Right. It's now four o'clock. I don't want to, that we missed the photograph, the picture that we'll do outside, right? So thank you for your attention and do not hesitate to enter in contact with me either through the list, the documentation list, the translation list or the IRC. Okay. So that we can really improve your software. Yes? Yes. We try to run a periodic hangout to discuss documentation issue. I used to call in advance for one week in advance. We tried to set a weekly meeting, but the attendance was very slow, so we decided to put every two weeks. I will restart this procedure and I would really like you to join us in this hangout so that we can set maybe a process of producing documentation and that one individual can help the other and we all move ahead together. Okay. Thank you for reminding me, Rio. This is important for us. Okay.