speaker: Olivier Thank you. Today, Laurent and I are going to talk about "Documentation as Code" and more specifically CI and CD for documentation. But first, let us introduce ourselves: Speakers: Olivier & Laurent - Short intro (NOTE: embed Olivier & Laurent's faces / OBS) Laurent: Hello I am Laurent, I also work for DXC Technology where I am acting internally as a DevOps Coach and externally as a CI and CD expert. I hope we will manage to show you the benefits of the CI and CD practices for documentation as code, as well as how easy it is to do it.

Back to this presentation. This presentation is an experience report, because we have learned so much from others through this format. This presentation is about our quest: the quest for great documentation. Previously, - our documentation was the last thing we would do, - it had spelling and syntax mistakes, - we were using the passive voice, but sometimes the active voice - it was often inaccurate, - a few were able to fix it and we had to contact them through email, - several authors could not work on the same piece of documentation without going through lengthy merges, - and links would break very often without us even knowing. Today, it's a very different situation - we have one service catalog and 174 services documented - documentation readers can contribute to the documentation using a Pull Request - we can report bugs and fix them - documentation changes go through a series of tests and gates - it's bigger yet more thorough and precise than ever - It has the same look & feel - it's written in the same style

The context for the experience report is our own company (but we do that with our customers too): - A platform which provides intelligence, orchestration, and automation capabilities to our managed service offerings - 630 contributors (developers, testers, scrum masters) - 1 "service catalog" site - 174 services documented

Speaker: Olivier We have 2 types of documentation: - Service catalog - Service documentation Service catalog: - Marketing / catalog site: mix of text, benefits, highlights, videos

Speaker: Olivier The documentation for each service leverages Mkdocs which we love because it's very close to markdown and does not require a separate git repository.

Speaker: Olivier

Fast, secure and cheap (static sites) - Comparing to WordPress/Drupal/Confluence type solutions - More secure (no DB to hack) - Portable (even offline) Easier to contribute to / keep up-to-date - The pull request / merge request workflow fully applies Battle test documentation Monitoring: - "Is this page useful?" - Analytics: like Google Analytics or Open Source alternative: Matomo - Reader journey, what is useful

speaker: Olivier

speaker: Olivier This video is a visualization of our service catalog repository documentation, as it evolves. In summary, we needed to build great documentation, at scale, battle tested and ensure it would not break over time. Looks like code to us!

Speaker: Olivier

Speaker: Laurent Hi, during the second part of the talk, I will give you a brief overview of the state of the art about CI/CD tools for documentation as code. Let's start with the development environment, which environment is required ?

Speaker: Laurent To write the documentation we use the Markdown language. Yes, I said language. Indeed, you write your documentation in your native language then you surround it with decorators which will modify the format. There is no need to have developer skills, the Markdown syntax is easy to use.

Speaker: Laurent Most of the integrated development environments (IDE) can be enhanced with multiple plugins. Here is a short list of what we used to use.

Speaker: Laurent GitHub offers an online VSCode instance attached to your GitHub repository. The Codespaces feature allows all the developer to share the same set of extensions as this configuration is automatically shared across the development environment attached to the project.

- Jekyll : Based on Ruby, it's hard to configure for a non developer users especially under windows => hard to contribute - Hugo: - HTML + go template for documentation - Far from standard markdown => hard for non dev users - shortcodes: like macro, for documentation. Ensures uniformity - Recommended if you need to have multiple page template in your web site - Marp: - Excellent to generate slide deck - Follow Markdown syntax - Presenter view - Template with CSS - Extensible - Output PPTX, PDF, PNG, JPEG - MkDocs: - Follow Markdown syntax - Closest to plain markdown, great for tech docs - Can integrate native HTML web page => Can integrate Marp outputs

Speaker: Laurent Use your favorite orchestration tool to deploy your documentation. Those tools now offer predefined features to ease your pipeline; We will see a set of GitHub Market Actions used in this documentation pipeline.

We use linters to check code "doc" quality. 2 types of linters - CLI: to be integrated in the pipeline - Editor: check syntax as you type, before commit and push

Identically, we can find CLI spell checker and Editor one Work with direction of exception and custom dictionary

Links must be checked regularly (cron) as they break without you doing any change.

Used to ensure your a vocabulary style guide.

You don't have to spin up a virtual machine or server to host your documentation site. Major Source Code Management applications already host web pages.

Speaker: Laurent We have been using GitHub template to ease the creation of Documentation As Code