Je migre vers un format de documentation plus pérenne

Depuis quelque temps, je reçois régulièrement des e-mails des lecteurs fidèles de ce blog qui veulent savoir pourquoi je ne publie pas de nouveaux articles. Voici donc un petit article pour donner de mes nouvelles à tous les visiteurs de ce site.

Vers le début du printemps, j’ai dispensé une formation Linux + Docker à une équipe d’administrateurs de FranceTV à Paris. J’avais donc le nez dans le guidon pour rédiger des supports de cours adaptés à cette formation. Pendant cette phase de rédaction, j’ai eu l’occasion de réfléchir au format de ma documentation technique. En effet, ces vingt dernières années, j’ai essayé toute une série de formats pour mes articles.

• les HOWTOs au format texte simple tels qu’on les trouvait dans le bon vieux temps sur tldp.org.
• les documents LibreOffice avec une feuille de style adaptée à la documentation technique, comme les manuscrits que je soumets à mon éditeur Eyrolles.
• les textes source en AsciiDoc, que j’utilise avec le Linux Professional Institute.
• ce blog qui tourne sous WordPress et construit avec un thème Hestia adapté.
• etc.

Et puis je suis tombé sur MkDocs, un générateur de sites statiques pour créer des plateformes de documentation. MkDocs est écrit en Python et transforme une série de fichiers écrits en Markdown en un site statique ergonomique et facile à organiser, même s’il contient des centaines voire même des milliers de pages de documentation. J’ai donc testé cet outil, ce qui veut dire que j’ai joué avec pendant quelques jours, jusqu’à ce que j’obtienne une présentation qui me convienne à peu près.

Pour m’entraîner avec MkDocs, j’ai décidé sur un coup de tête d’adopter l’outil pour la rédaction de mes supports de cours pour FranceTV. Le grand avantage, c’est que dorénavant, je ne suis plus obligé à me farcir l’éditeur WordPress. Au lieu de cela, je peux lancer mon éditeur de texte préféré (ah Vim bah ouais ah Vim bah ouais) et stocker mes sources en Markdown sur GitLab.

Évidemment, chaque solution a également ses désavantages qui lui sont propres. À titre d’exemple, je regrette un peu que Markdown n’offre pas la possibilité de mettre des bouts de code en exergue, du moins sans sauter à travers des cerceaux en feu. Mais bon, c’est bien une des rares limitations de l’outil.

En contrepartie, je gagne énormément en flexibilité et en pérennité. Une modification dans un article technique, c’est un coup de Vim et une paire de commandes pour actualiser le site. Et je n’ai pas à me soucier si mes docs restent lisibles dans dix ou vingt ans, vu que le texte simple et le Markdown m’ont l’air d’être faits pour durer. À condition qu’on n’ait pas tous succombé sous la chaleur d’ici-là, je dis ça parce que j’habite le coin de la France qui bat régulièrement les records de température.

Du coup j’en ai profité pour adopter l’outil MkDocs pour ma documentation interne également. Ce sont les HOWTOs de Microlinux, si vous voulez. Le destinataire de cette documentation, c’est tout d’abord moi-même, mais je pense qu’un administrateur système raisonnablement cultivé y trouvera des réponses à ses questions.

Retenez donc ces deux adresses, classez-les dans vos marque-pages et partagez-les allègrement.

• https://formation-linux.microlinux.fr
• https://docs.microlinux.fr

Quant à ce blog, je continuerai à m’en servir de façon sporadique pour des annonces comme celle-ci. Un gentil bonjour de la garrigue gardoise.

— Nico