Automatisation de la documentation¶

Générer, valider et publier la documentation automatiquement pour réduire la friction et garantir sa fraicheur.

Pourquoi automatiser la documentation¶

La documentation manuelle présente un deficit structurel : elle est produite par des humains qui ont d'autres priorités et oubliee dès que l'urgence passe. L'automatisation ne remplacé pas la documentation humaine, mais comble les angles morts et maintient la cohérence sur les éléments techniques.

Trois niveaux d'automatisation :

1. Génération : produire de la documentation à partir du code ou de la configuration
2. Validation : vérifier la qualité et la conformité de la documentation existante
3. Publication : déployer la documentation mise à jour sans intervention manuelle

Génération automatique¶

Infrastructure as Code¶

Les outils IaC peuvent générer leur propre documentation si les modules et ressources sont correctement annotes.

terraform-docs lit les annotations dans les fichiers .tf et produit un tableau structurée des variables, outputs et ressources. Il s'intégré directement dans un pipeline CI.

ansible-doc extrait les meta-informations des rôles Ansible (description, auteur, variables, tags) pour générer une référence consultable.

Documentation API¶

Pour les API internes, la génération à partir des spécifications OpenAPI garantit que la documentation est toujours synchrone avec le code :

• Les annotations dans le code source produisent la spec OpenAPI
• La spec OpenAPI alimente un portail de documentation (Redoc, Swagger UI)
• Le portail est publie automatiquement à chaque merge sur la branche principale

Documentation dans le pipeline CI¶

Intégrer la documentation dans la CI garantit qu'elle est mise à jour et validee à chaque changement.

graph LR
    A["Commit IaC / doc"] --> B["Lint markdown"]
    B --> C["Generation auto terraform-docs"]
    C --> D["Validation liens et structure"]
    D --> E["Build documentation site"]
    E --> F["Publication automatique"]

Étapes recommandees dans la CI¶

Linting de la documentation¶

Le linting détecté automatiquement les problèmes de qualité documentaire avant qu'ils atteignent la branche principale.

markdownlint¶

Vérifié la conformité syntaxique du Markdown : espaces inutiles, titres mal formates, listes incoherentes. Les règles sont configurables dans un fichier .markdownlint.json à la racine du dépôt.

vale¶

Vale est un linter de style textuel. Il peut enforcer :

• Un vocabulaire approuve (termes a utiliser, termes a éviter)
• Des règles de style (longueur des phrases, voix active/passive)
• Des règles métier (ne pas écrire "kill" pour un processus, utiliser "stop")
• Des règles de conformité (certaines expressions obligatoires pour les documents HDS)

Les règles vale sont définies dans des fichiers YAML et peuvent être versionnees dans le dépôt.

Règles custom¶

Pour les organisations avec des conventions spécifiques, les deux outils permettent de définir des règles personnalisees :

• Titres de runbooks doivent commencer par un verbe d'action
• Chaque page doit contenir un champ owner
• Les acronymes doivent être définis a leur première occurrence

Changelog infra¶

Un changelog d'infrastructure trace les évolutions de l'infrastructure dans le temps, distinct du changelog applicatif. Il répond à la question : "qu'est-ce qui a change sur notre infra cette semaine ?"

Générer depuis les commits IaC¶

Avec une convention de commits standardisee (Conventional Commits), un outil comme git-cliff ou conventional-changelog peut générer automatiquement un changelog structure :

Bonnes pratiques pour les commits IaC¶

• Un commit = un changement logique (pas "wip" ou "fix")
• Message en français ou en anglais, au choix de l'équipe, mais cohérent
• Inclure le périmètre impacte dans le scope : fix(prod/bdd): ...
• Referencez le ticket de changement dans le footer du commit