You know, personal, the story that we have on our open source tool, which is called CPAS,
which undertake a massive documentation, restructuration and refactoring in the few last
months.
And I'm going to explain what problems you faced, what solutions we had, and some advice
I can give to you.
Sorry.
Yes, that's a better.
Just a bit more of myself to present myself, so I'm a French developer, I'm a software
open source consultant.
I work in Britain, and they're East of France, at South of Hellenix, so we are a company,
a services company, specialized in open source software.
And together with AirT, so the French transport of electricity, we launched six years
ago, the CPAS CPAS project, which is under the governance and the LFNG, that I'm going
to present you today, and specifically, it's documentation.
Why it's not working.
Okay, so very quickly, what's the CPAS project?
I'm not going to the technical details, because that's not the matter here, but to explain
you, why we need it to undertake this refactoring, this documentation refactoring.
So the goal of the CPAS project is to run real-time virtual machines for electrical
substations.
So I put the schema on the left, on the right, sorry.
On top of the Linux kernel, you want to have VMs running at the top of it, and the goal
is to have electrical software and electrical applications running inside of it.
So it's all this stuff, it's measurement, it's a compilation of results, it's some alarm,
it's the management of the substations, so something very all this specific, but we do
not really, that I do not know specifically, because I'm more working on the IT side.
And all these people that are running specific applications inside of the VMs, once something
reliable, when something's cybersecurity, once some high availability and all this stuff,
to be able to run the software correctly.
So that's why we have all the rest of this software here, so mostly the virtualization
stack, some networking, storage, some resource storage and things like that, so, and
basically, all the requirements that we need it to have in order to put a navvizer into
a substation, so that people could run virtual machines.
One or two things very important to understand about this project, why is it to know that
it's not the perfect place, because not all people is looking at it, and when you have
multiple repositories, it's hard to understand, where to look.
The second thing, because we are using uncivil, we'll actually see is the uncivil documentation,
which is integrated in the code, so it's great because when you write code, you write a
small read me on top of your variables, and everything is displayed on the uncivil website.
Not gonna showcase that, that's actually the second picture, but it's great because it's
wiki as code, let's say.
And the last one was the Confluence wiki that was given by the LFNG framework, which was
contained at the time, the basic explanation of the project.
So the first question was, how do we divide the documentation into all of these three?
And what we decided is to try to keep the best of each tool, so the GitHub read me, as I
said, is mostly read by developers, so it should contain how to download the sources,
and how to build, basically, very very simple.
If you want to understand the bigger concept, if you're going to put all that together,
it's not exactly the place, the perfect place to do that.
It's really sources oriented.
The second one, so uncivil get access the wiki as code.
It should contain the thoroughly documented variables that we use on the uncivil side.
So it's also very IT specific, and it's not the general concept.
It's not the wiki, that's it.
The last one, we decided to keep the wiki on top of all of that, because it was structuring
the two others.
So it's the main entry point of the project, and it's where most, it was far more simpler,
and you have less communication between the pages.
So you don't have to read basically the entire wiki before understanding what you are doing
here.
This approach has one big downside, which is that when you don't know anything about
the projects, you can't really understand what's going on here.
So that's why we started first when we were structuring the wiki by looking at the different
categories, we decided to start with getting started sections, which is basically everything
that I'm just said to you is not true in this getting started sections.
So it's fairly straightforward way to have your seat as installed and running.
We've no fancy, fancy structure, no fancy configurations, just a default state, and you
have your seat as running.
And then you can go into the top extra structure that I just described to you.
So we also decided into the structure to keep the number of paths fairly just at seven
paths.
I think in the beginning we wanted to have like 15, and it was interesting from a documentation
point of view, but we just saw that people will not go into 15 points written in when
they first look at the wiki, so we wanted to keep the bigger paths small.
So here we have on this seven, and that was a better way to go for new people to understand
the wiki correctly.
Then the next very big topic that we struggle with that a lot is the naming of these
paths.
So that's basically the first thing that people will see is those titles, so what I just
so to you.
It's important to understand that specifically in our case, but I think also in many
projects, documentation serves two purpose, so you have the documentation side, which
is very simple, but you also have a bit of demonstration in your documentation.
So we want people to know why your project is good, and what it can do, because some people
are convinced by your projects, but they just don't know what your project is capable of.
And I think the main advice that we found here is that you better be understood in
the model by everyone than perfectly corrects.
One very simple example, so on the F, you have the first category, which is the main
ID, the second is the configuration, so that's where the end-sible paths come into mind,
and that's also where you're going to link into the end-sible galaxy stuff.
The third one is now that your infrastructure is deployed, how do you manage that?
So if you are an infrastructure management guy, you just have to look at the surface
basically.
So first one, first and third page.
Then you have, of course, always additional pages, because some topics require a bigger
explanation, also specific topics that only apply to that.
Same ID, it's technically not a bit weird, for example, real-time management, because
it's not exactly a management, you can configure the real-time information, but it's
better to have that even if it's not completely correct, it's better to have the same
structure for all the topics, so that's what we choose to do.
Last, so that's what the three main things that we decided during this week here
refactoring.
The last topic, I just wanted to highlight, because I think it's the right tool, the right room
presentation, so that's really great for them.
It's also pretty pretty, sometimes better, that's a very basic mug-down documentation.
It's also multi-person editing, so it can be great for that.
I think the main down part of Konflian's first that is not wiki as code, so it's really
hard to keep that updated, some people will make pears on C-pass and not update the
wiki.
Second, it's not related to versions, so it means that you can't have a wiki for the
one or one and a wiki for the one or two, today we just have a wiki for the main part
of C-pass, and when we have some specific things to do, we tell, okay, this is only available
for the one or things like that.
So there is actually a big question, and C-pass, whether or not we should switch from
Konflian's to also tool, like mouton, mark down, based tool, it's actually fairly complicated,
so yeah, it's not, we don't have a clear explanation for that today.
Okay, thank you for your attention, and I think we still have time for one or two questions,
maybe?
Two minutes.
Is there any question?
What is our team?
Ah, okay.
Okay, I repeat the question.
The question is, what is OT, maybe I should not have explained that, so I don't remember
the exact word, but basically OT is people that are, in our case, is the people that
are working on the electrical field, so they are dealing with electrical algorithm, and
they don't want to care about what is IT, so more computer science fake.
Other questions?
Yes?
Yes.
Well, the question is, what do you say is the main coding thing of the data control
of conference that makes the people so happy about it, so why they cannot move into all
such costs to adopt any?
Yeah, so the question is, what is the main feature of Konflian that may people stick to it?
I think, in our case, it's two things.
The first one is this, sorry.
So that's the first week we had, so it's hard to switch, of course.
But the second one, and I think it's very important for us, is that everyone can edit the
week, even people that are not computer science related, so OT people, that's what
I meant.
And that's actually pretty hard debates into the community, whether to switch or not,
because if you switch to GitHub based week, for example, you will lose a part of the community,
which is not computer science related guy, no gig guys, basically.
Okay.
Thank you everyone, if you have other questions, let me out of the door.
Thank you.