Industrialisation de la documentation technique : ~200 pages générées par code

Le contexte

Chaque brique de l'infrastructure a produit sa documentation : procédure d'installation, choix techniques et leur justification, captures d'écran commentées, incidents et leur résolution. Au total, de l'ordre de 200 pages.

Le premier rapport a été fait dans un traitement de texte. Le deuxième aussi. Au troisième, le problème est devenu évident : je passais plus de temps à recaler des images qui déplaçaient leur légende, à réaligner des tableaux et à harmoniser des titres qu'à écrire du contenu.

Le constat

Un traitement de texte mélange trois choses qui devraient être séparées : le contenu, la mise en forme et la pagination. Modifier l'une affecte les autres. Insérer un paragraphe en page 4 pousse une image en bas de la page 12, sa légende passe en page 13, et il faut tout reprendre.

Sur un document de dix pages, c'est agaçant. Sur cinq documents de trente pages qu'on reprend à chaque évolution de l'infrastructure, ce n'est plus tenable.

L'approche retenue

Traiter la documentation comme du code.

• Le contenu est du HTML structuré, écrit dans un script Python.
• La mise en forme est une feuille de style unique, partagée par tous les documents.
• La pagination est calculée par le moteur de rendu au moment de la génération, jamais à la main.

Le rendu PDF passe par WeasyPrint, qui implémente les spécifications CSS Paged Media — les règles conçues pour l'impression : sauts de page, en-têtes et pieds répétés, numérotation, veuves et orphelines.

Le bénéfice décisif : on ne met plus rien en forme. On déclare qu'un chapitre commence sur une nouvelle page, qu'une légende ne se sépare jamais de son image, qu'un en-tête de tableau se répète s'il déborde. Le moteur applique ces règles à l'ensemble du document, à chaque génération.

Ce que j'ai réalisé

Un module commun

Toute la mise en forme est centralisée dans un module unique importé par chaque script de rapport : page de garde, en-têtes et pieds de page, styles de titres, tableaux, encadrés, légendes de figures.

Corriger une couleur ou un espacement à un seul endroit met à jour tous les documents à leur prochaine génération. C'est exactement l'intérêt d'une bibliothèque partagée, appliqué à de la documentation.

Une charte visuelle définie une fois

Une identité cohérente sur l'ensemble des rapports : page de garde bleu marine, et deux types d'encadrés qui structurent la lecture.

• Encadré « pourquoi », en bleu — la justification d'un choix technique. C'est ce qui distingue une procédure d'une documentation : pourquoi cette option plutôt qu'une autre.
• Encadré « point d'attention », en orange — un piège rencontré, une conséquence non évidente, une précaution à prendre.

Les figures sont numérotées et légendées selon un format unique, avec une règle CSS garantissant que la légende reste toujours solidaire de son image.

Le traitement des captures d'écran

Une capture d'écran brute pèse plusieurs mégaoctets. Sur un rapport de trente-six pages, le PDF devient impossible à transmettre.

Le pipeline redimensionne chaque image à une largeur maximale raisonnable et la réencode avec un taux de compression choisi pour rester lisible à l'écran. Les images sont ensuite encodées et intégrées directement dans le document plutôt que référencées par un chemin de fichier — le script devient autonome, et le rapport se régénère à l'identique sans dépendre d'un dossier d'images.

La vérification automatique du rendu

C'est le point que je considère comme le plus utile de la chaîne, et le moins évident.

Générer un PDF ne garantit pas qu'il soit correct. Une image peut déborder, un tableau se scinder au mauvais endroit, une page rester blanche. Relire trente-six pages à l'écran après chaque modification n'est pas réaliste.

Le pipeline rend chaque page du PDF en image basse résolution, ce qui permet de contrôler la mise en page complète d'un coup d'œil — un aperçu planche contact du document entier. Le nombre de pages, la présence des figures et la structure sont vérifiés par programme.

On ne relit plus le document pour vérifier sa mise en page : on relit son contenu, et la mise en page est contrôlée automatiquement.

La reprise de documents existants

Deux besoins ponctuels ont demandé de sortir de la chaîne principale.

Modification de documents Word sans passer par Word : décompression de l'archive, édition directe du XML du document, recompression. Utile pour appliquer une correction identique à plusieurs fichiers, ou pour extraire des images d'un document dont on n'a plus la source.

Correction de texte dans un PDF sans source disponible : réécriture des flux binaires et de la table de correspondance des caractères. Une opération de dernier recours, mais qui évite de tout reprendre pour une coquille dans un document déjà diffusé.

Le résultat

Une chaîne de production documentaire reproductible : chaque rapport est un script, chaque génération est identique à la précédente, et une évolution de charte s'applique à l'ensemble en une modification.

Environ 200 pages produites sur l'ensemble du projet — installation et paramétrage des serveurs, structure de droits du serveur de fichiers, stratégies de groupe, politique de sauvegarde et déploiement de postes — toutes régénérables à l'identique.

Ce que j'en retiens

C'est le projet le moins spectaculaire de l'ensemble, et probablement celui qui m'a fait gagner le plus de temps.

La documentation technique est presque toujours traitée comme une corvée de fin de projet, faite une fois et jamais reprise — parce que la reprendre coûte trop cher. En rendant la régénération quasi gratuite, on change le rapport à la documentation : elle redevient un document vivant qu'on met à jour parce que ça ne coûte rien.

Et un principe qui dépasse largement le sujet : ce qui n'est pas vérifié automatiquement finit par ne plus être vérifié du tout. C'est vrai pour le rendu d'un PDF comme pour une sauvegarde.