Améliorer la documentation chez Magna-Power
Une seule base de code de documentation pour chaque produit actif, des références de commandes générées à partir du firmware, et des manuels publiés en HTML, PDF et markdown pour les outils d'IA.
Magna-Power propose plus de 300 000 SKU répartis sur dix séries de produits. Cette étendue résulte d'une planification rigoureuse à long terme et d'une ingénierie délibérée en faveur d'interfaces de programmation communes et d'assemblages configurables. La plateforme xGen exécute une seule base de code firmware pour les alimentations MagnaDC Série SLx, les charges électroniques CC MagnaLOAD Série ALx, le complément à diode de blocage Module BDx et le complément à haute stabilité Module DBx, avec un seul jeu de commandes SCPI et les mêmes interfaces de communication pour l'ensemble. Les alimentations MagnaDC des séries SL, XR, TS, MT et ML partagent de la même manière le même firmware et les mêmes fonctionnalités, avec des options communes d'une série à l'autre. Lorsque vous passez d'une série à une autre, la plupart des chapitres d'installation et de programmation décrivent les mêmes fonctions.
Une ingénierie partagée devrait signifier une documentation partagée ; pendant longtemps, ce n'était pas le cas. Chaque série avait son propre manuel, maintenu de façon indépendante. Une modification d'une interface commune devait être recopiée dans chaque manuel qui la mentionnait, ce qui entraînait des dérives de contenu. Un manuel recevait la correction ; inévitablement, d'autres ne la recevaient pas.
La culture d'amélioration continue de Magna-Power complique encore la situation. L'an dernier, l'équipe de développement xGen a produit près de 200 tickets de fonctionnalités et de correctifs répartis sur sept versions logicielles, et chaque changement visible par le client doit figurer dans les bons manuels, dans la même version, et être décrit correctement. Un processus qui repose sur le fait que quelqu'un remarque chaque changement et modifie manuellement plusieurs documents ne passe pas à l'échelle. Lorsqu'il prend du retard, c'est le client qui le découvre.
Nous avons donc reconstruit la documentation comme un système d'ingénierie : une seule base de code, des composants partagés, des compilations automatisées, des versions numérotées et des références de commandes générées à partir du firmware lui-même. La version Snapshot 75 de ce mois-ci intègre tous les manuels des produits actifs à ce système.
Une seule source, partagée par tous les produits
Chaque série de produits dispose de son propre projet de documentation, et chaque projet intègre plusieurs composants partagés, épinglés sous forme de sous-modules Git : la configuration de compilation et les outils, le thème HTML web, et une bibliothèque de contenu commune à sa famille de produits et à sa génération de produits.
La bibliothèque de contenu partagé est conçue pour éviter les doublons. Par exemple, le chapitre sur le refroidissement par eau se trouvait auparavant dans le manuel de la série TS, avec des copies modifiées ailleurs. Il n'existe désormais qu'une seule fois, et les manuels TS, SL et ML l'incluent tous. Les détails propres à chaque série, comme le connecteur de dérivation du liquide de refroidissement de la série ML, figurent sur cette même page et n'apparaissent que dans les manuels concernés. Une correction apportée au contenu commun atteint les trois manuels dès la compilation suivante.
L'équipe de Magna-Power a également opté pour des compilations strictes : les avertissements sont traités comme des erreurs, de sorte qu'un renvoi cassé ou une figure manquante bloque la publication au lieu d'être livré sous forme de lien mort. Cette contrainte garantit qu'une modification partagée ne peut pas casser silencieusement un manuel voisin.
Documentation des commandes générée à partir du firmware
Chaque commande SCPI est définie sous forme de données structurées dans le code source du firmware : syntaxe, paramètres et leurs plages, forme de requête, description et exemples. La compilation du firmware génère l'analyseur de commandes à partir de ce tableau. La compilation de la documentation génère le chapitre Programmation à partir du même tableau.
Le générateur de documentation sait pour quelle famille de produits il compile. Par exemple, l'alimentation dispose d'une commande pour activer sa sortie CC ; une charge électronique dispose d'une commande pour activer son entrée CC. Un seul jeu de définitions produit la bonne référence pour chaque type de produit, en listant les commandes que ce produit met réellement en œuvre.
L'avantage est le délai de traitement. Lorsqu'un ingénieur ajoute un paramètre à une commande, il modifie une seule définition. La compilation suivante du firmware accepte le paramètre, et la compilation de la documentation le décrit, en utilisant la description et l'exemple de l'ingénieur lui-même. Cette documentation issue du firmware s'intègre au processus de revue de code, ce qui garantit son exactitude et évite toute transmission à un tiers.
Compilée et publiée avec un flux d'intégration continue
Ce processus de compilation s'exécute sur le même serveur d'intégration continue interne que celui qui compile notre firmware, le logiciel MagnaCTRL ainsi que nos outils de test et d'étalonnage. La documentation est un artefact de compilation comme un autre : étiquetée avec sa propre version et regroupée dans le même snapshot de version que le firmware qu'elle décrit. Le Snapshot 75, publié ce mois-ci, associe le firmware 0.084 aux manuels SLx, ALx, BDx et DBx étiquetés.
Une seule compilation produit trois sorties à partir d'une seule source. Du HTML pour les manuels web. Du PDF composé via LaTeX, pour le manuel qu'un client imprime et classe avec un projet, et du markdown pour les grands modèles de langage. Une mise en page LaTeX commune régit la typographie, la numérotation des figures et des tableaux, ainsi que les renvois dans chaque manuel, jusqu'à la mise à l'échelle des dessins cotés sur la page et à l'interdiction de couper les noms de commandes avec un trait d'union en fin de ligne.
Les manuels web
Les manuels web disposent également d'un nouveau thème développé en interne, conçu pour s'accorder avec magna-power.com. Les dessins techniques sont tous des graphiques vectoriels, conçus pour s'agrandir correctement dans une visionneuse au clic, sans avoir à télécharger le PDF. Les exemples de code bénéficient de la coloration syntaxique et d'un bouton de copie. La navigation de gauche suit votre position pendant le défilement. Le mode sombre inverse les schémas au trait afin que les dessins noirs sur fond transparent restent lisibles, tandis que les logos et les photographies ne sont pas modifiés. Les encadrés Avertissement et Attention portent le symbole d'alerte de sécurité ISO 7010 dans ses couleurs standard dans les deux modes. Les polices sont hébergées localement, ce qui garantit un rendu cohérent lorsqu'un manuel est enregistré pour une consultation hors ligne.
Sélecteur de version de la documentation
Jusqu'à présent, seule la dernière version du manuel d'un produit était en ligne, et les anciennes compilations étaient écrasées. Si vous aviez mis en service un système avec un firmware antérieur et souhaitiez disposer du manuel correspondant à cette époque, il n'existait aucun moyen de l'obtenir (facilement).
Chaque manuel dispose désormais d'un sélecteur de version de la documentation. La dernière version reste à l'adresse habituelle du produit, et chaque version antérieure est archivée. À chaque compilation, le serveur d'intégration continue écrit un manifeste de versions à la racine de la documentation du produit, et le sélecteur lit ce manifeste au chargement de la page. Une page archivée affiche donc toutes les versions publiées depuis sa parution, y compris les plus récentes. Choisir une version vous amène à la même page dans cette version si elle existe, et à la page d'accueil de cette version dans le cas contraire. Les pages archivées affichent un bandeau indiquant quelle version vous consultez, avec un lien vers la dernière.
Les versions de la documentation sont numérotées séparément du firmware et sont associées par le biais du snapshot de version. L'archive commence avec cette version ; les compilations antérieures peuvent donc ne pas être disponibles.
Des manuels à confier à un assistant IA
Les ingénieurs confient de plus en plus souvent un manuel à un assistant IA pour lui demander de rédiger un script de test ou de décoder un registre d'état. L'extraction de texte à partir d'un PDF peut perturber l'ordre de lecture et la structure des tableaux, comme le montre l'exemple ci-dessous, qui utilise pdftotext, une bibliothèque Python courante, pour convertir une page d'un PDF.
Chaque manuel est désormais également publié en texte brut selon la convention llms.txt : un index à la racine du manuel, un rendu Markdown de chaque page à côté de son HTML, et un fichier concaténé contenant l'ensemble du manuel. Le formatage Markdown garantit que les titres, les tableaux et les blocs de code restent intacts. Les encadrés de danger apparaissent désormais sous forme de blocs étiquetés, et un assistant qui résume une procédure d'installation voit les mêmes avertissements qu'une personne. Les fichiers texte sont issus de la même compilation que le HTML, ce qui garantit qu'ils restent toujours synchronisés. Si cette étape échoue, c'est toute la compilation qui échoue plutôt que de déployer un manuel sans eux.
Considérer la documentation comme une partie du produit nous permet de reporter chaque amélioration dans tous les manuels concernés et de la publier en même temps que les fonctionnalités qu'elle explique. Les clients disposent ainsi de conseils cohérents pour leurs équipements, dans la version et le format qui répondent le mieux à leurs besoins.
Exemples de documentation de référence pour la série SLx, générés à partir de la même source :