Florent Zara – Training-as-Code: Scaling Open Source Literacy #FOSSBack

This lightning talk focuses on the approach Michelin has taken to develop reusable training materials. The speaker discusses the decision to use AsciiDoc, a lightweight markup language, for creating training content that can be customized while maintaining a generic core. AsciiDoc offers a predictable specification and advanced features such as modular content with includes, variables, and macros, which makes it suitable for collaborative and version-controlled training documentation. The benefits of using AsciiDoc include the ability to generate multiple output formats, including slides, PDFs, and static websites, and its adoption in other large projects like Git and Red Hat documentation. The speaker outlines the current state of the training materials and future plans for broader community engagement and documentation sharing.

This lightning talk is a small spin-off from what you for those who were there a few couple of minutes ago introducing the what we've done at Michelin so training as car just to give you a bit of background. So within the Michelin sport and building the training programs we decided that the generic part is going to be made public because we had kind of we did not

want to win for the the wheel and to write from scratch training materials for people at Michelin. So we this and it was complicated to find find something that can be easily reusable which is not a PDF or PowerPoint slides markdown docx files that can be easily reused and then when you can put your specifics what's specific to Michelin and to the internal processes. we decided to

build to look at the resources available and to build a new training program a new training project that will be given to a foundation the generic part and then to be able to include the specifics of Michelin and then the generic part can be reused by anyone easily just as easily as we are doing at Michelin. So the we want to treat the training materials also like

it's software source code as easily as that. So we chose to do it in AsciiDoc. So why AsciiDoc? Because it's for those who don't know you know maybe markdown this just like markdown a lightweight markup language but to the contrary of markdown this is well defined predictable there is a well defined predictable specification with markdown you don't have many flavors and this is managed by the Eclipse

Foundation you know with a strong governance about the to write specification. There are some advanced native features we can leverage for build this kind of training materials like includes, so we can break down the the training materials into smaller parts that you can choose to include or not inside your own uh training program. Uh, the con- conditions, variables, macros, uh stuff like you find sometimes in in

programs in uh software. Uh, this is supported by a large set of tools like we you've got uh plugins, extensions for IDEs, text editors, uh software forge uh like GitLab, GitHub they support Uh there were generic converters Pandoc for those who knows you can convert for nearly everything every format to every other format and uh AsciiDoc is supported and there is a dedicated tooling ecosystem with AsciiDoc

to Antora, uh Kramdoc, etc. etc. And for those who don't know that is also AsciiDoc is used in large uh projects like the Git project documentation. If no need that's uh AsciiDoc. Uh for example Red Hat product documentation is done using AsciiDoc. Uh the Eclipse documentation of course is done because we are kind of dog fooding. So, as you see that's this is something we we put

it we want to be collaborative by nature. So, the text this is just basically text. Uh this can be version control, you can track changes, you can review contribution from the community. And you can put review processes and it's far far more far more easier than uh using the uh review or the the contribution mechanism from uh Word of Google Workspace or any online tool online online

tool you can think of. With one single source, so the AsciiDoc files, the text files, you can generate multiple outputs. You can generate slides using Reveal.js or PDF, you can generate a PDF document. Uh you can generate a static website with all your content uh like you can publish it on a on on your internal website or external website. You can generate a ePub if you want

to have some kind of electronic book. Uh docx, ODT uh files. You you you just name it and if you don't have your favorite uh file to convert it uh you can add an extension to your favorite converter. So, the content structure using include as I said can be modular. You can just break down in like at the open source history the so you can have a

small module, you can have bigger modules for a story, you can include exclude some part of your your content. You can just write your own specific and then use just an include uh directive inside your your your training program. This is already used so as I said at Michelin I use it also at engineering school to do trainings in in France at engineering school and I think

that some government entities in France are also going to use it. And so for the road map uh we currently have the awareness module which is online. Uh I still need to put some more documentation, more content of course on contribution in open source on open source. So, the content is there. I still need to make it available to the community. It's still in still internal And

uh to have a project website to showcase how it is done. So, just Eclipse OSILK open source and inner source learning guild OSILK uh online and just I'm here the two days if you have more questions. Thank you.