 Welcome all to the session. I am Divya. I work for Red Hat Bangalore India. Today we have been talking about how the documentation should be and I am going to talk about the tools which we can use throughout the documentation life cycle to ensure we document everything. Okay, let's get started with the session. These are some of the tools we use in our product documentation life cycle and we use Trello. It is a freeware if you would like to use an open source tool. Instead you can try Kanban board or something. Trello is an application that helps you to keep track of everything, my new details to big picture and we use Bugzilla. I am sure all of you know Bugzilla. I am not going to talk about what Bugzilla is. I am going to just share information on how you can customize Bugzilla to collaborate better and ensure everything gets documented. The other tool we use is wiki. We use wiki for creating a doc plan and get sign off so that all the stakeholders know what is going to go in the documentation for a particular release. We have the other tools called a publican. I think most of you would have heard about it. It is a single source tool. Using publican you can create multiple formats. I am going to share about what we are exploring. Going forward with the documentation something called Junkins. Junkins cat is a tool. Let's get into the details of each of these tools. I am not going to compare Trello with any other application. Maybe I am going to just talk about... You might need to move it a little bit closer or look a little bit like that. Can everyone hear? Can everyone hear now? Is that a bit better? Take your throat. See how you go. The handheld one. Can you hear me better? Can you try that one? No? There is a button here. Yeah, so as long as that is green. I will just take this one out. Sorry. We want to be able to hear. Put your hand up if you can't hear very well. Trello with the tool we use during planning phase. Planning phase is very important. If you are working on a documentation project, especially in the planning phase, you would be bombarded with information. Sometimes the information would come during meetings. Sometimes it would be in emails and other stuff. Trello will help you to put all the details together in a tool that would help all the stakeholders to get the required information. Trello is easy to use and all you need is just an internet access and an account. Creating an account is as easy as your email account. All you need to do is ask all your team members and other stakeholders to create an account and then get going. I will just show you the GUI office so that you would know what it would be. Just in case you didn't... I was not using Trello before. So my condition would be something like this where I used to make notes and say red color. I'm going to assign it to X person, green color. I'm going to assign it to Y person. So Trello has helped me to categorize things better. So this is an example here where you can categorize things. You are documentation project have something like administration guide and you want to work on installation guide and stuff. You can create a board for administration guide and add cards for each feature. And Trello allows you to add members to the card so you know whom you are assigning to. And you can also add other things like checklist. So you want to say to complete this documentation maybe you want the writer to complete ABC thing. So you can add it to a checklist and assuming you have an attachment instead of sending it over an email you can attach the file. So in case the writer wants to know more about it or any more information they just have to come to this card rather than searching it in an email. So you can also set due dates in Trello. This is one example of using Trello. Another example could be you can create a Kanban board. We also use this Trello for managing our sprint management. The other example could be usage of Trello could be as simple as collecting opinions. Maybe you want to come up with your department goal for the year. You can ask your team members to add cards for their each idea. And if you ask them to vote you would know what people are interested. This would help you to know what are department goals and easy to set the goals. The other example could be maybe you might be making notes now. Maybe in case you have a Trello account you can just create LCA 2015 and start adding points. So you would know what you wanted to learn or what you learned using Trello. So these are some of the cool features. I think you can use it for anything and everything. So once I come up with a task and that is which needs to go in. What we do is we create bugs. Some of the examples could be once we decide feature X has to be documented in the administration guide. We go ahead and create a tracker bug for that particular feature. And we would start adding concern stakeholders here. So that they get to know the status as to when the documentation is updated. The other reason of adding a tracker bug for a feature documentation could be is easy to collaborate as well as to give status update to the stakeholders. As you mean you say you're working on feature X. You can add your developers and QA team as well as your project managers or whoever is concerned. And you can use bugzilla to collaborate. When you request inputs from the engineering team maybe you can add a bugzilla comment so that the user would give you inputs in the bugzilla itself where it doesn't have to happen over an email. Once you complete your documentation maybe you can send it again for review using bugzilla. So you don't have to send a mail to your manager or somebody has to tell hey look I've done with my documentation. I'm waiting for inputs or even you're done with the review comments. So you really don't have to dig your emails. You can use bugzilla to collaborate with engineers and other stakeholders. The other thing what we could do here is during the planning phase assuming your engineers have around 400 bucks to fix in this release. So how would you know which of them has to be documented? Unless you know you really can't plan your documentation project well. So what we could do is an example here is request doc text. Maybe you can request your engineers to set that field similar to that field. Maybe if they think that this their bug fix or an enhancement could have a doc impact. They can set it to question mark. And once you document it you can set it to place so that they know that their enhancement or the bug fix has been documented. And other customizations what we have done is we have used something called a doc type could be a bug fix or enhancement or it could be a known issue. So imagine a developer wants to add a bug as a known issue and he really don't know whom to contact to or he doesn't have to worry about whom to contact. He just have to set the doc type to known issue and provide input. So the document team can just query for doc type is equals to bug fix as a known issue and then they can just come up with the known issues for the release. So this helps in collaboration even if the engineer doesn't know whom to contact as long as he provides input in the bug so the documentation can pick it from there and document it. Once we have our tracker bugs as well as we know what needs to be documented we use Biki to create documentation plan. I'm sure most of you all of you know about Biki. So I'm not going to tell what Biki is. I'm just going to show you an example of a documentation plan we have created. Here we're going to give a summary of what is this release about or project about. What are we achieving and also say from which release doc will be updated to which release and at the guide level we're going to list which feature is going to get documented who is the doc owner or the responsible writer along with the contacts. We can also add bug links assuming that you query for 200 engineering bug fixes which has doc impact maybe you can add it here so that if a project manager or a product manager wants to know what all docs are going to get updated for the release they can just look up for this plan so they would get an idea as to what is going to get added in this release. So once we know what has to be documented we use a tool called Publican. Publican is a single source publishing tool. It mainly supports XML inputs and if you have inputs I mean you collect inputs in ASCII or any other format probably you can use Pandoc to convert into XML and then publish using Publican. Publican is easy to use like it's a CLI. All you have to do is YAM install Publican to install your Publican and once you install it you can just create a book using Publican which gives you a template which has all the basic information ready like the revision history, the book information, the author information and other details and a sample chapter. Once you update create more chapters you can just run Publican build command and provide the formats you want. It supports HTML, single HTML, PDF and many more formats. You can also use Publican to create your documentation website and manage it, not just put an output. Publican also supports localization of files in case you want to translate into multiple languages. It does produce .po files and .pot files. You can use that. If you want to see an output of who uses Publican or is it easy to manage a docs project? Yes, you can see Fedora Docs project to see how Docs website is managed using Publican. Publican is mainly packaged for Fedora, Debian and Ubuntu and it's known to be worked on Windows, OpenSource and other operating systems as well. To get a complete list of commands or how to use Publican you can just refer the user guide. We use Publican. We create documents using Publican and update the PDF in the bugzilla and request for review comments. Once we fix the review comments and then say here was this is where the documentation is available for this feature. This is what we have been doing now. If you see the documentation, we have to run commands and do so many things here. Though it is simple, we are looking at improving the documentation process. At the moment we said we are going to improve the process. Most of us felt, wow, our documentation is perfect. The process is perfect. How do we improve? If you think that it would not be working. We also have something called a Brands in Publican which determines what brands are available or how they look and feel of it. On the repository, there is a common brand which is the moment you install Publican. It creates a default brand. There are other brands also available. You can create your own brand and depending on the brand you have created depending on the CSS style sheet, the format or the look and feel of the docs would look. To show you an example, this is the PDF format generated using Publican for one of our guides. Now we know what Publican is. I can just list some of them who already use Publican. Like Red Hat, Fedora and Pacemaker. Some of them use Publican. Some of them manage with their websites as well using Publican. Once we were using Publican, we thought authors are concentrating on authoring the document as well as publishing the documentation. We wanted to keep two things separate and we were looking at improving the process. If you think the document process is perfect, I don't think it works. During time, we also have to change. Otherwise, this would be what happens. There are so many tools which are coming up to automate so many things. Unless you improve or change, it doesn't help. What we are planning to do now, we are exploring options of using Junkinscat, which is a tool which are modified for Red Hat. Junkinscat tool is a front-end for Junkins. Junkins takes care of the weightlifting. Technically, it takes care of the metadata and other stuff. We are integrating Junkins, which automatically builds the documents as and when they're updated. Maybe we said as and when you add your files to the JIT repository. Maybe every five minutes, it has to publish the documents to the staging server as and when it is done. Junkinscat can also support DocBook, Mallard, Markdown, ASCII Doc, and so many other markup languages. You can create using any of the markup languages and publish it. We can increase the volume. Is the volume still quite low? Yes. Sorry, if we can take a second. I don't know how much time you've got. Can you talk and see if that's better? Yes. Hello. If you can talk and see. Can you talk? Can you tell me now? Yes. Okay. What we plan to do is we plan to create different views for different audience. Here is an example of the work-in-progress site. What we plan to do is, if the developer is planning to access, he's going to get an option of only a report-a-bug and access to the documentation. When a writer logins, he should be able to see the link to the repository and when was it last built and information. You can decide which format the output should be. Should it be an HTML or a PDF or whatever format you would be. This will help to give you the different views for the different users. Okay. That's all I had. Do you have any questions or suggestions or you want to share anything? Yes. So how are you linking the content that you have on MediaWiki with the publishing tool that you're using at the moment? Public and I think it was. If it is in the ASCII format, we just use PanDoc to convert it to ASCII doc and then we are creating a tool which Jenkinscat, we are modifying it so that even the input is in XML or ASCII. You can still build it in any other format you want. It's an internal configuration.