Contextes difficiles
L’idée d’optimiser la rédaction de documents est née dans la précipitation des tâches quotidiennes. Les fréquents passages entre les pipelines, le monitoring, l’automatisation, le RnD, le support et le suivi minutieux du temps ne permettaient pas de se concentrer sur la documentation.
Journaliser l’historique
J’avais besoin de journaliser mes actions, d’enrichir les textes avec des images, des liens et des timestamps, sans laisser de chevauchement de sujets au sein d’un même brouillon. Il fallait organiser cela de manière à pouvoir facilement retrouver l’évolution des travaux plus tard.
Plusieurs fois, le journalisation de Putty/Bash a permis de retrouver une séquence de travail délicate sur le serveur de production. N’ignorez pas cette possibilité.
Publication
Plus tard, j’ai voulu transformer ce brouillon en document opérationnel et le publier dans la documentation projet. Résultat : j’ai pu sortir bien au-delà des limites initiales.
L’objectif était de créer des brouillons avec un formatage étendu et de travailler avec la documentation comme avec du code.
Cela a permis d’économiser du temps sur le formatage et la conversion vers un format standard de publication.
Format en ligne
Au final, le format Markdown + Git a permis de générer automatiquement une documentation en ligne. En bonus, un mode hors ligne, accessible via le cache du navigateur. Dans les réseaux fermés du client, en avion ou là où il n’y a pas d’internet, ce mode s’est révélé très utile. Les clients l’ont aussi apprécié.
Le format Markdown est utilisé dans Gitlab, YouTrack, certains messageries et est reconnu par toutes les modèles LLM.
Brouillons partagés
Si votre travail n’est pas lié aux finances, vos brouillons ne doivent pas être cachés. Au contraire, permettez à d’autres de collaborer dessus.
Mon désir de rendre les brouillons accessibles a été un catalyseur pour la création de « documentation comme code ». L’équipe DevOps s’est débarrassée des fichiers texte anonymes et des problèmes de recherche, « où cela a été noté ? ». Pas de problèmes de versions Word différentes, de fichiers images disparates, etc. De plus, à partir d’un brouillon, on obtient directement une version en ligne et un PDF élégant et rigoureux.
La documentation aujourd’hui
- Écrite en Markdown (éditeur Typora ou équivalent avec autosauvegarde + commits dans IDEA/PyCharm)
- Stockée dans Gitlab (accessible à tous les employés selon les rôles, supporte l’édition multi-utilisateurs)
- Générée automatiquement en version en ligne dans un conteneur Docsify (mise à jour du code toutes les minutes) ; les sites sont publiés sur internet via DNS
- Facilement exportable en PDF avec un formatage identique, Vue.js pour le site comme pour le fichier
- Les diagrammes sont créés en format Drawio (outline) et Mermaid (inline)
- Les diagrammes sont exportés en SVG (et occasionnellement en PNG pour les plateformes non compatibles) et incluent le code source intégré
Ce qui manque encore ?La plupart des utilisateurs ne s’intéressent pas à un seul endroit centralisé où la documentation est stockée, ni à la possibilité de la modifier en mode multijoueur. Il y a très peu de contributeurs éditeurs, mais beaucoup d’utilisateurs simples. Pour eux, il est crucial de trouver rapidement le document souhaité, dans sa version actuelle, et de pouvoir le partager facilement. Cela soulève plusieurs questions, notamment :
- Comment générer automatiquement une liste de la documentation.
- Comment classer les liens dans le texte selon la pertinence des documents (pas en fonction de la fraîcheur des modifications, mais de leur pertinence réelle — car personne n’a besoin d’un document en tête de liste uniquement à cause de modifications cosmétiques).
- Autoriser un mode de modifications mineures directement dans le document, sans avoir à manipuler les sources.
- Mettre à jour la documentation « par lots », lorsque certaines parties sont interconnectées et partiellement ou totalement réutilisées.
- Générer automatiquement la documentation, car elle devient très rapidement obsolète.
- Assurer la cohérence non seulement de la documentation, mais aussi de rappeler la nécessité de corriger ou compléter les réponses publiques des collaborateurs dans les canaux publics ou communautaires. L’opinion sur l’autorité d’un individu est souvent formée à partir de ses réponses — les mots d’une personne ayant un lien avec la documentation ont un poids bien supérieur à la documentation elle-même, ce qui est un fait établi.
Le troisième point est déjà présent sur certaines plateformes, comme Discourse. L’IA pourra aider à structurer la documentation.