WEBVTT 00:00.000 --> 00:10.400 You know, personal, the story that we have on our open source tool, which is called CPAS, 00:10.400 --> 00:14.680 which undertake a massive documentation, restructuration and refactoring in the few last 00:14.680 --> 00:15.680 months. 00:15.680 --> 00:20.080 And I'm going to explain what problems you faced, what solutions we had, and some advice 00:20.080 --> 00:21.080 I can give to you. 00:21.080 --> 00:22.080 Sorry. 00:22.080 --> 00:27.680 Yes, that's a better. 00:27.680 --> 00:32.720 Just a bit more of myself to present myself, so I'm a French developer, I'm a software 00:32.720 --> 00:33.720 open source consultant. 00:33.720 --> 00:38.040 I work in Britain, and they're East of France, at South of Hellenix, so we are a company, 00:38.040 --> 00:41.760 a services company, specialized in open source software. 00:41.760 --> 00:47.360 And together with AirT, so the French transport of electricity, we launched six years 00:47.360 --> 00:54.000 ago, the CPAS CPAS project, which is under the governance and the LFNG, that I'm going 00:54.000 --> 00:58.480 to present you today, and specifically, it's documentation. 00:58.480 --> 01:01.720 Why it's not working. 01:01.720 --> 01:06.160 Okay, so very quickly, what's the CPAS project? 01:06.160 --> 01:10.200 I'm not going to the technical details, because that's not the matter here, but to explain 01:10.200 --> 01:14.800 you, why we need it to undertake this refactoring, this documentation refactoring. 01:14.800 --> 01:19.800 So the goal of the CPAS project is to run real-time virtual machines for electrical 01:19.840 --> 01:20.800 substations. 01:20.800 --> 01:23.840 So I put the schema on the left, on the right, sorry. 01:23.840 --> 01:30.680 On top of the Linux kernel, you want to have VMs running at the top of it, and the goal 01:30.680 --> 01:36.560 is to have electrical software and electrical applications running inside of it. 01:36.560 --> 01:40.880 So it's all this stuff, it's measurement, it's a compilation of results, it's some alarm, 01:40.880 --> 01:45.560 it's the management of the substations, so something very all this specific, but we do 01:45.560 --> 01:51.840 not really, that I do not know specifically, because I'm more working on the IT side. 01:51.840 --> 01:56.680 And all these people that are running specific applications inside of the VMs, once something 01:56.680 --> 02:02.360 reliable, when something's cybersecurity, once some high availability and all this stuff, 02:02.360 --> 02:04.160 to be able to run the software correctly. 02:04.160 --> 02:09.800 So that's why we have all the rest of this software here, so mostly the virtualization 02:09.800 --> 02:18.160 stack, some networking, storage, some resource storage and things like that, so, and 02:18.160 --> 02:23.680 basically, all the requirements that we need it to have in order to put a navvizer into 02:23.680 --> 02:28.000 a substation, so that people could run virtual machines. 02:28.000 --> 02:31.480 One or two things very important to understand about this project, why is it to know that 02:31.480 --> 02:36.400 it's not the perfect place, because not all people is looking at it, and when you have 02:36.400 --> 02:39.680 multiple repositories, it's hard to understand, where to look. 02:39.680 --> 02:43.560 The second thing, because we are using uncivil, we'll actually see is the uncivil documentation, 02:43.560 --> 02:47.040 which is integrated in the code, so it's great because when you write code, you write a 02:47.040 --> 02:51.680 small read me on top of your variables, and everything is displayed on the uncivil website. 02:51.680 --> 02:57.600 Not gonna showcase that, that's actually the second picture, but it's great because it's 02:57.600 --> 02:59.440 wiki as code, let's say. 02:59.440 --> 03:06.400 And the last one was the Confluence wiki that was given by the LFNG framework, which was 03:06.400 --> 03:10.680 contained at the time, the basic explanation of the project. 03:10.680 --> 03:15.040 So the first question was, how do we divide the documentation into all of these three? 03:15.040 --> 03:20.720 And what we decided is to try to keep the best of each tool, so the GitHub read me, as I 03:20.720 --> 03:25.960 said, is mostly read by developers, so it should contain how to download the sources, 03:25.960 --> 03:28.240 and how to build, basically, very very simple. 03:28.240 --> 03:31.240 If you want to understand the bigger concept, if you're going to put all that together, 03:31.240 --> 03:34.160 it's not exactly the place, the perfect place to do that. 03:34.160 --> 03:36.720 It's really sources oriented. 03:36.720 --> 03:39.200 The second one, so uncivil get access the wiki as code. 03:39.200 --> 03:43.840 It should contain the thoroughly documented variables that we use on the uncivil side. 03:43.840 --> 03:49.280 So it's also very IT specific, and it's not the general concept. 03:49.280 --> 03:51.560 It's not the wiki, that's it. 03:51.560 --> 03:56.560 The last one, we decided to keep the wiki on top of all of that, because it was structuring 03:56.560 --> 03:57.560 the two others. 03:57.560 --> 04:02.600 So it's the main entry point of the project, and it's where most, it was far more simpler, 04:02.600 --> 04:04.920 and you have less communication between the pages. 04:04.920 --> 04:08.280 So you don't have to read basically the entire wiki before understanding what you are doing 04:08.280 --> 04:10.440 here. 04:10.440 --> 04:14.360 This approach has one big downside, which is that when you don't know anything about 04:14.360 --> 04:17.960 the projects, you can't really understand what's going on here. 04:17.960 --> 04:24.240 So that's why we started first when we were structuring the wiki by looking at the different 04:24.240 --> 04:29.920 categories, we decided to start with getting started sections, which is basically everything 04:29.960 --> 04:34.200 that I'm just said to you is not true in this getting started sections. 04:34.200 --> 04:39.480 So it's fairly straightforward way to have your seat as installed and running. 04:39.480 --> 04:46.400 We've no fancy, fancy structure, no fancy configurations, just a default state, and you 04:46.400 --> 04:47.400 have your seat as running. 04:47.400 --> 04:55.200 And then you can go into the top extra structure that I just described to you. 04:55.200 --> 05:02.160 So we also decided into the structure to keep the number of paths fairly just at seven 05:02.160 --> 05:03.160 paths. 05:03.160 --> 05:09.720 I think in the beginning we wanted to have like 15, and it was interesting from a documentation 05:09.720 --> 05:15.760 point of view, but we just saw that people will not go into 15 points written in when 05:15.760 --> 05:20.600 they first look at the wiki, so we wanted to keep the bigger paths small. 05:20.600 --> 05:26.600 So here we have on this seven, and that was a better way to go for new people to understand 05:26.600 --> 05:29.040 the wiki correctly. 05:29.040 --> 05:36.280 Then the next very big topic that we struggle with that a lot is the naming of these 05:36.280 --> 05:37.280 paths. 05:37.280 --> 05:42.840 So that's basically the first thing that people will see is those titles, so what I just 05:42.840 --> 05:44.840 so to you. 05:44.840 --> 05:48.840 It's important to understand that specifically in our case, but I think also in many 05:48.840 --> 05:52.600 projects, documentation serves two purpose, so you have the documentation side, which 05:52.600 --> 05:57.360 is very simple, but you also have a bit of demonstration in your documentation. 05:57.360 --> 06:01.400 So we want people to know why your project is good, and what it can do, because some people 06:01.400 --> 06:05.840 are convinced by your projects, but they just don't know what your project is capable of. 06:05.840 --> 06:11.880 And I think the main advice that we found here is that you better be understood in 06:11.880 --> 06:15.200 the model by everyone than perfectly corrects. 06:15.200 --> 06:20.040 One very simple example, so on the F, you have the first category, which is the main 06:20.040 --> 06:24.880 ID, the second is the configuration, so that's where the end-sible paths come into mind, 06:24.880 --> 06:30.000 and that's also where you're going to link into the end-sible galaxy stuff. 06:30.000 --> 06:34.440 The third one is now that your infrastructure is deployed, how do you manage that? 06:34.440 --> 06:38.000 So if you are an infrastructure management guy, you just have to look at the surface 06:38.000 --> 06:39.000 basically. 06:39.000 --> 06:40.880 So first one, first and third page. 06:40.880 --> 06:44.560 Then you have, of course, always additional pages, because some topics require a bigger 06:44.560 --> 06:48.760 explanation, also specific topics that only apply to that. 06:48.760 --> 06:54.440 Same ID, it's technically not a bit weird, for example, real-time management, because 06:54.440 --> 06:59.280 it's not exactly a management, you can configure the real-time information, but it's 06:59.280 --> 07:02.360 better to have that even if it's not completely correct, it's better to have the same 07:02.360 --> 07:09.320 structure for all the topics, so that's what we choose to do. 07:09.400 --> 07:15.320 Last, so that's what the three main things that we decided during this week here 07:15.320 --> 07:16.320 refactoring. 07:16.320 --> 07:21.320 The last topic, I just wanted to highlight, because I think it's the right tool, the right room 07:21.320 --> 07:24.320 presentation, so that's really great for them. 07:24.320 --> 07:31.320 It's also pretty pretty, sometimes better, that's a very basic mug-down documentation. 07:31.320 --> 07:34.320 It's also multi-person editing, so it can be great for that. 07:34.320 --> 07:40.040 I think the main down part of Konflian's first that is not wiki as code, so it's really 07:40.040 --> 07:46.000 hard to keep that updated, some people will make pears on C-pass and not update the 07:46.000 --> 07:47.000 wiki. 07:47.000 --> 07:50.800 Second, it's not related to versions, so it means that you can't have a wiki for the 07:50.800 --> 07:55.600 one or one and a wiki for the one or two, today we just have a wiki for the main part 07:55.600 --> 07:59.760 of C-pass, and when we have some specific things to do, we tell, okay, this is only available 07:59.760 --> 08:03.080 for the one or things like that. 08:03.080 --> 08:07.280 So there is actually a big question, and C-pass, whether or not we should switch from 08:07.280 --> 08:13.080 Konflian's to also tool, like mouton, mark down, based tool, it's actually fairly complicated, 08:13.080 --> 08:18.080 so yeah, it's not, we don't have a clear explanation for that today. 08:18.080 --> 08:22.480 Okay, thank you for your attention, and I think we still have time for one or two questions, 08:22.480 --> 08:23.480 maybe? 08:23.480 --> 08:25.480 Two minutes. 08:25.480 --> 08:27.480 Is there any question? 08:27.480 --> 08:28.480 What is our team? 08:28.480 --> 08:29.480 Ah, okay. 08:29.480 --> 08:31.480 Okay, I repeat the question. 08:31.480 --> 08:35.680 The question is, what is OT, maybe I should not have explained that, so I don't remember 08:35.680 --> 08:41.120 the exact word, but basically OT is people that are, in our case, is the people that 08:41.120 --> 08:45.040 are working on the electrical field, so they are dealing with electrical algorithm, and 08:45.040 --> 08:49.040 they don't want to care about what is IT, so more computer science fake. 08:50.040 --> 08:53.040 Other questions? 08:53.040 --> 08:54.040 Yes? 08:54.040 --> 08:55.040 Yes? 08:55.040 --> 08:56.040 Yes? 08:56.040 --> 08:57.040 Yes. 08:57.040 --> 09:02.040 Well, the question is, what do you say is the main coding thing of the data control 09:02.040 --> 09:09.040 of conference that makes the people so happy about it, so why they cannot move into all 09:09.040 --> 09:10.040 such costs to adopt any? 09:10.040 --> 09:15.040 Yeah, so the question is, what is the main feature of Konflian that may people stick to it? 09:15.040 --> 09:18.040 I think, in our case, it's two things. 09:18.040 --> 09:19.040 The first one is this, sorry. 09:19.040 --> 09:22.040 So that's the first week we had, so it's hard to switch, of course. 09:22.040 --> 09:26.040 But the second one, and I think it's very important for us, is that everyone can edit the 09:26.040 --> 09:30.040 week, even people that are not computer science related, so OT people, that's what 09:30.040 --> 09:31.040 I meant. 09:31.040 --> 09:36.040 And that's actually pretty hard debates into the community, whether to switch or not, 09:36.040 --> 09:41.040 because if you switch to GitHub based week, for example, you will lose a part of the community, 09:41.040 --> 09:46.040 which is not computer science related guy, no gig guys, basically. 09:48.040 --> 09:49.040 Okay. 09:49.040 --> 09:52.040 Thank you everyone, if you have other questions, let me out of the door. 09:52.040 --> 09:53.040 Thank you.