 I had to walk the table to fit in the 50 characters because it was much much longer and I used every allowed character for that. So I work at Red Hat but there is no Red Hat logo in the presentation because I work at Corporate Fingy. I've been involved with software for quite a while and currently I'm doing technical writer stuff which is new for me and I'm doing that for Eclipse Che which is an idea for for the cloud. I've been in a bunch of communities before and from this past I have some tools on some manner of doing things that makes that I'm not a normal technical writer. I'm really sorry about it. And I changed the name of my jobs but basically it's always the same. You are paid to do something that you don't know anything about but at the end you explain to people how they should do it. So a little bit of context. Now we have some upstream project which is called Eclipse Che and we are not talking about the project but about the documentation. So the documentation is AsciiDoc with some injection inside of it and it's transformed into a HTML to make a website and it's also transformed into a web archive to be embedded into the application. Good. So far so good. And we have a downstream product which is called CodeReady Workspaces and I issue where we are a couple of hours ago. You are explaining how we do our product documentation and how that. So basically he said it all. I don't have to put some details on it now. That's perfect. A perfect day. And so basically we take AsciiDoc to transform it into XML, into Dogbook XML and at the end we get HTML, APub and pf. So that's the starting point and the output. Good. When I was asked to do some downstreaming we had a script which was there, which was focused on doing that for the previous release and I have an objective to be creative, start from scratch, automate as much as possible and if we can do more one release with the script it would be awesome. And another useful information. We are a little bit less than three writers. So we have two writers full time and three other people who have maybe one day a week to help us. And on the other side we have lots of developers. Until this morning I thought there were 50 plus. It seems they are less but they are still doing a lot of things. So they are doing fast and they are changing every day what they are doing and they don't tell you they forget that it's documented somewhere. So that's the context. That's moving target. This guy made a wonderful presentation about what it is to live in this context where you're not sure. Maybe it was right yesterday. Maybe today it changed. You don't know. And so let's take the stream metaphor. That's upstream. So we are getting in the stream. And that's how we want to have downstream. Where everything is already done upstream and we don't have to do anything anymore. So luckily we start from a project which has already decided to go for modular documentation. It means we have files organized in assemblies and modules, modules which are concepts, procedures or reference modules. You can look at the talk from Yaronia before if you want to have more information about that. And we are using ASCII doc and we will massively use some of the features that we have inside of it. It is to include files and it is to have some attributes to have different contents depending on the context. We have also some tools. So we have a tool which is called NewDoc and which is a really awesome tool because if you look at the modular documentation thingy you must do this and this and this and that. It's a lot. NewDoc, it's just you do NewDoc minus, minus procedure and you get the title of your procedure and you have a template with everything inside of it, all the attributes that you need, all the stuff that you don't have to think about it anymore. It's automated. It's okay. And you can concentrate just on the content. Problem, yes. The writers know that this tool exists. The contributors don't. So what do we have to do now? And that's currently one challenge of the project is to raise awareness of this tool is existing for the people who are contributing. So how we will do it, future will tell. Now it's just we know that it sucks and we know that we have to improve on that. Over tool, TestDoc, that's also a really good tool because once you have, at the beginning we have a template. The template at the beginning is very fine and is particularly correct. But then you write stuff or the contributors or the people who are writing stuff and at the end it's an S and it doesn't build and you will discover it too late, always too late. So this tool, same thing, same problem is the writers, the professional writers have knowledge of this tool and they use it and now what we have to do is to raise awareness in the community so that people are able to use it and at the moment, for example, to install it, there is no automated process to install it. So there are some improvements. That's the tool that comes from my previous job is I was working on a monocle project and they use a tool which is a Python tool to automate testing and there is a, it's easy to configure, it's much more easy to use than a bash script and you have an output that you can handle correctly. So for me, the main feature of TOX is that you write a unique file which is something that is not complicated to write even for a non-engineer guy and that when you run it, you have an output where when the output is not necessary, so when it builds, you have zero output, except it works. And when you have a problem, then you have thousands of lines of garbage with one useful information inside. So that's to prove that it's not so complicated to use TOX. So I'm sorry, it's late in the day, we'll have bleeding eyes at the end but there is a lot of code here. So basically that's all the commands that we want to run to build our downstream documentation and we want to validate as much thing as possible. We use more validation tools as necessary but it's just if one validation tool fails, we want to have the other one react correctly. So basically we do all of that. Maybe I will not be very detailed on what the tools are. And the output for all of that is just okay, it builds and it's five line of output so your eyes are not too much tired of seeing that. So automating the building of the guys and removing the output when it's okay, that was the first step. Second step is we have the upstream documentation and we want to transform it to the downstream documentation. And for that we have one script which is currently a batch script which does all sorts of things that I will be in detail later and what we want to do is we execute that script and then we build the documentation. And thanks to TOX we have things that get really separated so all the stuff that we have done before automating the building documentation we can use it here as a modular step in the downstreaming process. And that's something where the three dots here normally it's a thousand lines of output to tell you where it did fail. It doesn't fit in the stream. So I removed it. But basically here we know that currently and that's the situation as of today if we don't stream the eclipsed documentation, the installation guide is building, the mid discussion guide is building and the end user guide is broken and it happens every day. So that's one of the challenges now. It's building upstream. It's broken downstream. And the last one is to have the same tool able to get a fresher version of upstream into the downstream stuff. So this one is easy stuff. And there is nothing special about it. So now that's cool because we have, let's say for the major structure we have one tool that does the job and that is quite okay for the eyes. And that's, let's get a little bit more in detail into this filter script. So what we want is that we have some ASCII doc modules. We have all of these modules that are grouped to make a full user story or a full guide. And what we want is at the end some complete title with a lot of inputs. Good. That's what we want. What we have is Jekil Yamel. So it's that kind of stuff. So sometimes you have a navigation where the chapter is only one part and sometimes you have some folder items. So sometimes you go, you are going in the first level. Sometimes you have to go in the second level. That's a problem. The second problem is you are pointing to a URL, not to a file name. It means that you have to find the file name again. So that's something which is not very convenient. But let's say we have to live with it. There are other tools like Antora which are much more easy to downstream because the navigation is using directly the file names. So you don't have to look and search for the file names. So here come also some tooling that I have from my previous slide. So I was doing a lot of Ansible playbooks for five years. So when you do a lot of Ansible playbooks, you do a lot of Jinja. And this time, it was the first time that I was using Jinja directly without Ansible. And basically this bunch of characters is how to pass all the things. So we have to use the manifest Jekyll Jamal to transform it into a manifest almost Askidoc Redefine. And then we have to find in our Askidoc files when they are integrated in the menu. They all have a little header, which is not Askidoc, which is some Jekyll metadata. And the Jekyll metadata that gives us this permalink, which is the final URL for the file. So what we have to do is to get the oldest permalink that we have in every file to guess the file name. That's something that is a tedious work. But we have the tools to do that automatically. So once it's done, you don't have to think about it. And since we have that, we never had a build broken because of these twins. We never had a problem with the Jinja template. We never had a problem with all the set that we have. All the other problems were really structural problems in the content. So that the upstream is very relaxed with the content where you can have missing cross-reference and missing links and missing things. Okay, it builds. And that downstream is not able to cope with that. So we cannot handle having missing cross-references. But that's the previous thing was for the content that is completely present upstream. But we have a guide which is a little bit special, which is the installation guide where all the content is downstream. Or most parts of the content is not present upstream. So for this one, automating is not possible. So you end up with a very static file. And we try to make comments into the downstream repository so that you offer to yourself, remember that, ah, yes, this file, I am able to edit it. And oh, this file, I'm not allowed to edit it. So let's get a little bit closer. So now we have taken all the files from upstream. We have moved them in downstream. That was the first step. Then we have generated the master file, so the file which is taking on all the modules and all the assemblies and putting them together. Now we can start with the contents. So first iteration, we look at all the files that we have now downstream and replace all of the world that is not correct anymore. We have two situations here. We have one part which is quite technical. It is that upstream we have links. And what we want to have downstream is X-reference. So we have to transform the nature of the bits that we have inside. And one of our parts is that we have things like the name of the project, which is not the same downstream. For this one, it's quite, so we have an easy solution. It's that once we have identified all of the stuff that is always moving, we can replace in the upstream documentation directly all the things that we need to change by the attribute. So now the moving bits are dynamic. Then last part is to still have upstream a script that is running and that will, when a contributor will put the non-attribute product name or the non-attribute something, that will replace it by the correct attribute. So let's say it's here is that avoiding a human error by having some automated process to say, hey, no, you don't say Eclipse Shea. You say Prod short. But when you write it, you can still say Eclipse Shea because it's easier to do. You know that then you can run a script that will transform it for you. So make your life easier. And then we have the most complex stuff. It's when it's not in just one line that needs to be changed but a complete check of text. And then for example, these are the example outputs. If you want to show what is the output of a command and the output of a command is completely different upstream and downstream, then you can use inclusion and attributes again and use the project context attribute to do some inclusion that will go over a different file. So that's cool also. Same thing for the screenshots because obviously most of your screenshots will be different because the product name will be different things like that. So that's easy game. That's a lot of work. You can tell about it. But technically speaking, it's just a matter of time identifying the screenshot that you need to change all of that. It's a tedious work but it's something that we can do. And then last thing is that we have some things where putting them in an external file makes things complicated because then if you have to look into your paragraph and then look in a different file and look it again you lose your mind. So in that case we do some things that are maybe less pure but in terms of technicality but which are easier to understand when you are passing the test as a human being. So here the human is still the person who needs to understand what is going on. For now, so the funny thing is that when I started it, I started it in November or October or November and I was thinking I would be ready, it would be completely finished when I do the talk in January. And that's not the case. It means that for now, that's where I am in the downstreaming. We have delivered one major version with that and I believe that we have some new things that will come later. So this is what are the current challenges for me. One is that we fail too late. We fail on the downstream product and each time, for now it's each week we have new requests upstream and we will discover that the content is impossible to build for the downstream product when we are doing the downstreaming. It means each time that you do, we have new content upstream. We want to get it downstream. We launch a script and it breaks and you have to fix it. So now one thing that I would like to do is to make sure everybody is using a new doc to create new modules so that the new content is already correct because it's not human to write the super long idea that we need with your little hands. Second thing is to use the tools that are able to validate the content already upstream. It means that we have to do it. We have to talk with the community so that we get accepted and all of that, it's quite a walk. And one other thing is I'm starting late as a technical writer and passive voice my first month I don't understand when I was doing a pre-request I got 50 remarks of this is not proper English this is your passive voice you have this and that I don't understand what you mean it was hell, it was like you're happy, you have written a super thing and then what you get is just negative feedback because it's not proper English. That's not good. And then now in my editor I have added every linter that I could find that are working on the editor and I follow the advice of all of them once not any linter is saying that it's bad then I will commit that thing and I'm sure that every single person on health will say, yes you're compliant with every style, guys. And now and that's here something that I believe in and maybe I'm completely wrong and maybe I will have to change my mind sooner or later I believe that it would be a nice thing to have leaders working and giving feedback in the upstream curve to do all these basic language check that can be automated because that's basically then you follow all the advice of the linter and you have something that's pretty okay and if the linter is giving you bad advice you follow it and it cannot be wrong so I don't know and that's I'm thinking about it because in my previous job when I was doing uncivil playbooks and when I started to playbooks at some point I was using the molecule project and what's the first thing that they do they are lending your code and they are saying you hey, this is not the way to look and they are thinking that yes but it works okay then follow the linter just follow the linter and it makes your life easier because it's so the content is less personal not a problem and basically you have less a negative feedback when you do a public request so now that's my current situation is okay now we should do that and at the moment I believe that Vale is one of the most active linter in the world I request your feedback from the audience what are you using and I finished very very soon so now it's really time for a discussion so do you use linter which linter are you using do you use no linter and why production I rather just read it a bunch of times and you are a writer professional writer because it seems to me that professional writers don't want linter but developers want linter and who is writing the documentation and the project developers so this is an audience that needs this help more than professional writers they have all the knowledge already they have these magic eyes which detect all the errors I know these are my colleagues for example I come from engineering and I'm blind I'm super blind for these things what's the time of that process of what of lending the time of going through a game where you're making sure that it passes what you think it takes all your life ah demo time so to go that's these things in my editor I have these things which is listening problems and basically it's just I'm getting all these list of things until it's zero and there are a lot which are completely completely okay but then that's easy this one where is it this one quick fix add to folder dictionary this is a little so it's it's a false positive but now it's fixed for the rest of the time so it means that now I should have somewhere some file that was generated that says never bother me again with this thing but so and we have a lot of passive voice it's important because passive voice I use it all of the time I never see it but now I have this little yellow thingy that tell me hey Fabrice you're a bad boy and I see that the spell checker is never happy with all the worlds that are super legit in my so I'm super angry against the spell checker but the the passive voice detector it's setting my ass every day because I'm sorry English is not my primary language so I don't think about I don't think about it the project is already super complex just understanding what I'm talking about so when I'm talking about stuff and just being focused on that is just enough but making sure that my language is correct that's too much I'm a super lazy guy so I want to write and have tools that tell me hey no that's not correct I know that these tools are limited but I prefer to have some let's say the 80% which are really crap and that should never happen on the internet so because each time that I put passive voice into GitHub I feel bad I show to the world that I'm not able to distinguish passive voice from active voice it's a what should I be get fired for it no because you know it's before I started this job that was the thing that was the most difficult for me now I will write English my wife is British I don't understand why she's speaking I said you know not in British English but in some international English that I know the vocabulary I have 300 words of vocabulary it's fine but because now I know that everybody in the world is understanding me because I use 10 words the first time I was doing documentation the documentation was written by a friend who is British and after it was written okay so paragraph number one what are you telling me this is happening it's not happening because it's a native so you use double negation everywhere and he's happy with that I don't know now I see the ground cover of my little girl and when he's speaking and when he's not able to say yes or no but he uses double or triple negation in one sentence which is 5 minutes long to answer to me and say okay was it in yes or no so and it's for me it's the same for me here and in the project we are two full-time writers plus three one day in a week writers and they have 30 or more developers and they should write some documentation for the future they may do it very well but we need to help them because if we don't do that just think that now we are already running like crazy after all the futures and after the documentation they are getting quicker every day we will die because now the backlog at least our backlog in the documentation will go and it's like oh and then exactly what you said what was written two months ago that was for the previous three years because it still works today so we need to have to use better the time for the technical writers we need to use it better and we need not to use our times writing stupid comments on GitHub about hey this is passive voice and arguing about it because that's the answer hey passive voice I don't care the information is here okay you want me to rewrite it and then we rewrite it for them but it means that we will take let's say a massive amount of our workload doing things that they could do by themselves with some assistants like that because they are only using the same editor and and and it makes it's building confidence also because when you see that you have no problems in what you have written you have someone so you have some tool that has validated what you did so you can build up confidence and say I managed to write 10 lines and there is no passive voice and I know that there is no passive voice because these two have told me they didn't detect it so maybe there is one that it was very difficult to find one it means that maybe that's something I believe in and maybe it's not true so I will tell you next year if we manage to implement that and if it works but I believe that this way you can also educate your community and get people to do things that are super afraid of doing and I believe that here I'm using also all my experiences because it's starting with 40 plus to be technical writer they are all super proficient in English and you are like that I understand the tool but when I write a sentence it's boring that's a for me that's something that we and that's changed a little bit the work of technical writer because you are facilitating the work for more people and it's like you are adding more ants to your ants yeah if yeah that's the story of giving a fish and learning to fish and we have tools for that now that's good I think that you also are just saying on the guidelines upstream that you make this part of your process or we go for everything so first thing is we have we have CI running so we have continuous integration so it's first thing is to find the right tool so that's also my question here what is the right tool? I don't know what to follow here because too many writers that are super educated and don't need that but it's like I believe they need a good tool then implementing that so that it works first on my laptop then do a request and tell other people they should use it and then add it as a informative step in the continuous integration and then when it starts to be smooth on and make it an informative step in the continuous integration, it's like if it's positive voice political voice, no, never blocked things like that when we are right there, really it's good and then at least say that's an idea but it's set up the project that it already works on the Eclipse Shea editor where you can add all of these extensions that do the stuff in your editor and then it's easy, it's okay if you want to edit the doc you go on the Shea.openship.io you load this file it will load the documentation it will load an editor with all the plugins that you need to do the meeting and it's done on the it's done directly on the on the work space of the developer and that's yeah, that's really cool because that's this tool is able to enforce a project to help a project enforce the way people are working because nobody can say I didn't see it yeah, okay no, you use our tool so you use Eclipse Shea to write the doc and we have set up everything so that you can write it with some thousands of helpers and then so that's cool for the project because we have one use case where it's the right thing to do and it's empowering the people to work and but on another project it's not an idea but here this use case is just perfect for the project so let's try that I have to convince everybody people in my team the people in the community so there is a lot of work for that but yes and the other thing is docs that's cool because I will show you a complete demo time so that's cool, yeah you don't see everything happening it's but you have the output only for the thing that failed because it's I love continuous integration but what I hate is when you have more than 20,000 lines where you have to search and where I like this to be so that is now I have in my blogs I have only the things where there is the error and it means that one fourth of the output that I have would have normally and there is everything that I need to create a ticket for my colleague here to say hey fix upstream and it's also an easier step for me so to say hey now we can please fix upstream, I can put the logs there are only 200 lines not 2,000 and they can work on it and we can work as a team also and it's the 5 minutes before Q&A we are already in Q&A about questions I don't know how we should use time can you please repeat the question the question is time train to implement all of that I would like to do it in December but in December I had to fix that multiple times every day so I ended up just doing this loop the situation of broken upstream fixing upstream don't worry so now that's currently our program is this one we are spending most of our time fixing upstream so it means that getting these tools working upstream is really very high in the priority for me because it's it's taking less time so it will be different for different tools because our continuous integration is running on Q&A so it means that if we want to integrate things in the continuous integration we need to have things that run in a container so it's the test attack tool for example it's a GitHub project and you need to the installation of the tool is not integrated into the project itself so to create a container for that is just it's not it's not done in two minutes there is not already a container we have to do that so that makes things a little bit so it's more problematic but it's a bash kit so it's basically pasting one file in the right place so it's an easy work it's just creating the right container and then publishing the container in the right place so it means for us so now I have the rights to publish the image for Eclipse chip so already all the bureaucracy to get something published is done and it could be the most time-consuming thing because now if I just publish a new version of our Shadox builder image we have the future and then it's a matter of adding a line in the Toxini file so it's done in half a day something like that for one step for one tool for a veil so for choosing a little I have a problem because it's choosing a little for a project and just when it will be chosen it will be difficult to change afterwards so that's why now I'm asking people what are you using and and because it's now it's now that we will decide and once the decision is made it will be a little bit too late to change to change decision so one thing that I'm currently investigating does someone has implemented the Red Hat Style Guide as a veil test test as a veil test so is someone already done that normally that's how it works in the world if you have one idea there is at least one person with exactly the same idea at the same moment so maybe someone has done that and what I'm currently looking is okay we did that and where is it and if I don't find it I will do it myself but normally it should be it must be somewhere and and because I can't do it the first to have this idea that's not possible I'm not as fast as that is it should exist so it must exist I have to find it or if it doesn't exist I have to do it but it's I'm a lazy person we need to search the time not the space to say what? search the time of the space the time I need to find it in the time yeah sounds like a plan any other question I'm open I find the discussion very interesting so more more from my colleagues how do you decide with the downstream or you just take everything that a few writers do or you pick up something specific that's a bad question so until December we did something which was really easy once it's in a master in the upstream we take it downstream and now we have some new features that are arrived into upstream that are not presented into our downstream products and that's when it starts to be really not a good time in a question of time it means that for every pull request that happens on the upstream we have to read the pull request and we have to say this one we can back to downstream that's a new feature we cannot so we have to set up a process for that we have to start doing that and that was I don't know when you have 50 pull requests in a day to do that sometimes it's how will I do that so like we leave it where it is and we will take we will cherry pick the pull request that are really important to get in the downstream we don't really know how we should do that but we don't know not how to do that but how to get the time to do it completely and correctly for now it's a matter of time if I have to read every pull request and to select all of them it will get completely crazy so that's we have a problem now and same problem as you said that a feature arrives now or later and you have to remember when you have to put it in the documentation that's exactly our problem it's and that's something that you can automate but I don't know how maybe you can how will you do that so you know exactly when you can integrate the feature in the official documentation okay same thing everywhere it's not a perfect science and I believe that nobody expected to be a perfect science and now it's QA time over thank you