Documenter son infrastructure, c'est rendre intelligibles ses choix, ses schémas et ses procédures pour que d'autres puissent l'exploiter et la faire évoluer. La meilleure documentation vit près du code et reste à jour.
Points clés
- Docs as code et schémas en code
- ADR et décisions tracées
- Runbooks et documentation générée
Docs as code et schémas en code
On versionne la documentation en Markdown dans le dépôt, à côté de l'infrastructure. Les schémas se décrivent en code avec Mermaid ou Diagrams (Python), ce qui les rend diffables et maintenables, contrairement à une image figée. Cette approche docs as code garantit que la doc évolue avec le code via les pull requests.
ADR et décisions tracées
Les Architecture Decision Records consignent chaque décision importante : contexte, options envisagées, choix retenu et conséquences. Un ADR court par décision, daté et numéroté, évite de réexpliquer mille fois pourquoi tel outil a été choisi. C'est une pratique simple mais transformatrice à enseigner.
Runbooks et documentation générée
Pour l'exploitation, on rédige des runbooks : procédures pas à pas pour les opérations courantes et les incidents (redémarrer un service, restaurer une sauvegarde). Côté infrastructure as code, des outils comme terraform-docs génèrent automatiquement la doc des variables et outputs des modules, évitant la doc obsolète.
En pratique
Scénario. Atelier de 2 heures : sur une infrastructure existante (le homelab du parcours), les apprenants produisent un schéma Mermaid, un ADR justifiant le choix du reverse proxy, et un runbook de restauration de sauvegarde. Ils génèrent aussi la doc d'un module Terraform avec terraform-docs. Livrable : un dossier docs/ versionné contenant schéma, ADR et runbook.
Questions fréquentes
Pourquoi écrire la doc en Markdown dans le dépôt plutôt que dans un wiki séparé ?
Parce qu'elle évolue alors avec le code via les pull requests et reste synchronisée. Une doc dans un wiki séparé devient vite obsolète et oubliée.
Qu'est-ce qu'un ADR et quand en écrire un ?
Un Architecture Decision Record documente une décision technique importante et ses raisons. On en écrit un dès qu'un choix structurant est fait (outil, pattern, fournisseur).
Pour aller plus loin
Pour approfondir : Apprendre terraform pas a pas · Automatiser avec ansible. Et le reste de nos ressources pour les écoles, OF et formateurs.
Besoin d'un formateur expert ou envie de transmettre ?
tonformateur connecte les écoles et organismes de formation avec des intervenants experts du terrain.
Voir les cours à pourvoir Explorer l'annuaire d'outils →