Qui, dans l’équipe, sait exactement ce que fait la ligne dix du script de sauvegarde nocturne, et pourquoi elle exclut certains dossiers précis ? Cette question, posée un jour où la personne qui avait écrit ce script était en congés lors d’un incident, a révélé un problème classique : un script parfaitement fonctionnel, mais compris par une seule personne dans toute l’équipe.
Le risque d’un script qui fonctionne sans être compris collectivement
Un script maison bien conçu rend d’immenses services au quotidien, mais sa valeur réelle diminue fortement si une seule personne peut l’ajuster ou le corriger en cas de problème. Ce risque reste invisible tant que tout fonctionne normalement, et se révèle brutalement le jour où cette personne est indisponible, ou a quitté l’équipe, précisément au moment où un incident demande une intervention rapide.
Pourquoi un document externe séparé ne suffit pas
La réponse la plus fréquente à ce problème consiste à rédiger un document séparé décrivant le fonctionnement du script. Cette approche présente une faiblesse structurelle : le document et le script évoluent rarement au même rythme. Une modification du script, faite dans l’urgence, oublie presque toujours de mettre à jour le document correspondant, qui devient alors trompeur plutôt qu’utile, ce qui est pire qu’une absence totale de documentation.
Une méthode légère : documenter dans le script lui-même
La documentation qui reste la plus fiable dans la durée est celle qui vit directement dans le fichier du script, sous forme de commentaires ciblés, plutôt que dans un document externe consulté séparément. Cette proximité physique augmente fortement la probabilité qu’une modification du script s’accompagne d’une mise à jour du commentaire adjacent.
#!/usr/bin/env bash
set -euo pipefail
# Ce script sauvegarde la base de données et les fichiers médias
# de trois sites clients avant leur mise à jour hebdomadaire.
# Exécuté chaque lundi à 3h par une tâche planifiée cron.
# Le dossier "cache" est exclu de la sauvegarde des fichiers :
# son contenu est régénéré automatiquement après restauration
# et alourdirait inutilement l'archive de sauvegarde.
rsync -a --exclude="wp-content/cache" "$SOURCE" "$DESTINATION"
# Le paramètre --no-dev évite d'installer les dépendances
# de développement, absentes en environnement de production.
composer install --no-dev --optimize-autoloader
Ce qu’il faut documenter en priorité
Documenter chaque ligne d’un script serait contre-productif et découragerait sa relecture. La documentation doit se concentrer sur ce qui n’est pas évident à la simple lecture du code : les décisions prises, les raisons d’un choix précis, les conséquences d’une modification imprudente.
- Le contexte général : à quoi sert ce script, à quelle fréquence et par quel mécanisme il s’exécute.
- Les décisions non évidentes : pourquoi tel dossier est exclu, pourquoi telle option précise a été retenue.
- Les conséquences d’une modification imprudente : ce qui casse si une variable est mal ajustée.
Compléter par une transmission active, pas seulement écrite
Les commentaires réduisent le risque, mais ne remplacent pas complètement une transmission active. Faire relire le script par une autre personne de l’équipe, en lui demandant d’expliquer ce qu’elle en comprend sans aide, révèle rapidement les zones encore floues que les commentaires n’ont pas suffisamment éclaircies.
Un script compris par une seule personne n’est jamais totalement fiable, même s’il fonctionne parfaitement depuis des mois.
Un test simple pour vérifier que la documentation suffit vraiment
Une fois les commentaires ajoutés, un test révélateur consiste à demander à une personne qui n’a jamais touché au script de le modifier volontairement, pour ajouter par exemple un quatrième site à sauvegarder, en ne s’appuyant que sur les commentaires présents. Si cette modification aboutit sans intervention de l’auteur original, la documentation remplit réellement son rôle. Si elle échoue ou nécessite de poser des questions, c’est le signe que certains commentaires restent trop elliptiques ou supposent une connaissance implicite du contexte que seule la personne qui a écrit le script possède encore.
Pour aller plus loin
Cette discipline de documentation légère, appliquée systématiquement à chaque script maison créé dans l’équipe, évite d’accumuler une dette de connaissance invisible qui ne se révèle qu’au pire moment. Elle ne demande ni outil supplémentaire ni processus lourd, seulement l’habitude de commenter ce qui mérite de l’être, au moment même où le script est écrit ou modifié.
