Documenter les clics ne sert à rien : l'outil les enregistre déjà
Quand quelqu'un cherche comment documenter des automatisations, il finit presque toujours par faire la même chose : des captures d'écran de l'éditeur, un pas-à-pas de quel module suit lequel, et une description de chaque nœud. Un après-midi entier de travail. Et c'est du travail jeté, parce que tu recopies à la main la seule chose que l'outil sait déjà tout seul.
Make, n8n, Zapier ou Power Automate te montrent le graphe du flux en deux clics : ce qui le déclenche, ce qui vient après, quel champ se mappe avec quel champ. C'est vivant et toujours à jour. Ta capture, non : elle périme dès que l'éditeur déplace un menu ou change la couleur d'un bouton, et à partir de là elle documente une interface qui n'existe plus.
L'effet secondaire est pire que le décalage. Une documentation qui a l'air vieille cesse d'être lue, et dès qu'elle cesse d'être lue, tout le monde suppose que le reste ment aussi. Un manuel que personne n'ouvre est exactement aussi utile que pas de manuel du tout, sauf qu'en plus il faut l'entretenir.
Le graphe te dit ce que fait le flux. Il ne te dit jamais pourquoi. Et le pourquoi n'est nulle part, sauf dans la tête de celui qui l'a monté.
Le bus factor : si une seule tête sait pourquoi, c'est ça ton vrai risque
Le bus factor d'un système, c'est le nombre de personnes qui peuvent partir avant que plus personne ne soit capable de le comprendre. En automatisation d'entreprise, ce nombre vaut presque toujours un. Une personne a monté le flux, cette personne sait pourquoi le seuil est à 48 heures et pas 72, et c'est cette personne qu'on appelle quand il se passe quelque chose de bizarre.
Pas besoin d'un bus. Des vacances, un changement d'équipe, un arrêt long ou une meilleure offre suffisent. Et le plus gênant, c'est que le flux ne casse pas —ce serait facile à repérer— : il continue de s'exécuter ponctuellement tous les jours. Ce qui casse, c'est ta capacité à le modifier.
Ça se voit bien avant que le désastre arrive. Les symptômes d'un bus factor à un sont toujours les cinq mêmes :
- Personne ne touche au flux. Les modifications se collent par-dessus, dans un nouveau flux, parce que modifier l'original fait peur.
- Chaque changement métier ouvre un débat archéologique. « Et ça, pourquoi c'est comme ça ? ». Personne ne sait, donc on laisse tel quel.
- Un doublon apparaît. Quelqu'un monte un autre flux qui fait presque la même chose, parce que repartir de zéro coûtait moins cher que comprendre celui qui existait.
- On ne peut pas expliquer une décision. Un client ou un auditeur demande pourquoi le système a fait ce qu'il a fait, et la réponse honnête est qu'on n'en sait rien.
- Le flux se fige. Quand la personne s'en va, il reste allumé et personne n'ose ni le modifier ni l'éteindre.
Remarque qu'aucun de ces cinq symptômes ne se soigne avec une capture d'écran de l'éditeur.
La seule chose à écrire : la règle métier
Une règle métier, c'est la décision humaine que le flux prend en ton nom pendant que personne ne regarde. Ce n'est pas « si le champ statut vaut en attente, envoyer un email ». C'est : « un client qui n'a pas répondu depuis 48 heures reçoit une relance, parce que le contrat type promet une réponse sous deux jours ouvrés et qu'on ne veut pas le rompre ; sauf s'il s'agit d'un grand compte, auquel cas c'est le chargé de compte qui est alerté et pas le système ».
Tout le reste —le module, l'ordre, le mapping des champs— c'est de l'implémentation. Ça change le jour où tu changes d'outil et il ne se passe rien. La règle survit à l'outil : si demain tu migres de Zapier vers n8n, la règle est la seule chose que tu dois emporter, et c'est précisément la seule qui n'est écrite nulle part.
Pourquoi cette condition et pas une autre
Chaque chiffre présent dans un flux vient de quelque part : un engagement de service, une promesse commerciale, une exigence légale ou —le plus souvent— une réunion d'il y a deux ans. Écris lequel. « 48 heures parce que c'est le délai promis par le contrat type » est une condition qu'on pourra revoir le jour où le contrat change. « 48 heures » tout court, c'est un chiffre intouchable que personne n'osera jamais bouger.
Quelle exception elle couvre
Les branches bizarres d'un flux ne sont presque jamais un caprice : ce sont des cicatrices. Ce filtre qui écarte les commandes en dessous d'un certain montant est là parce qu'un jour une série de tests est passée et a pollué la facturation. Écrire la cicatrice évite les deux choses qui arrivent quand elle n'est pas écrite : que quelqu'un retire le filtre par « propreté » et que l'incident revienne, ou que personne n'ose y toucher alors que la raison d'origine a disparu depuis des années.
Qui elle alerte et ce qui se passe si personne ne répond
Ce qui explose en production, ce n'est généralement pas la logique : c'est la fin ouverte. Un flux qui escalade vers une personne doit dire vers qui, par quel canal, sous quel délai — et ce qu'il fait si cette personne ne répond pas. Si la réponse est « il attend indéfiniment », c'est aussi une décision et il faut l'écrire, parce que le jour où une commande reste bloquée une semaine, quelqu'un demandera si c'est un bug ou le design.
Collées à la règle viennent trois données qui ne sont pas du métier mais qui se perdent tout aussi facilement : le propriétaire —une personne avec un nom et un prénom, pas un service—, les identifiants qu'il utilise —quel compte, à qui, avec quels droits— et les systèmes qu'il touche, en séparant ce qu'il lit de ce qu'il écrit. Ce qu'il écrit, c'est ce qui peut te retourner le CRM un mardi après-midi.
C'est ici que ce guide frôle la gouvernance et le contrôle de l'automatisation sans se confondre avec elle. La gouvernance pose les droits, l'audit et le frein à main : c'est du contrôle. Ici, c'est de la connaissance. Tu peux avoir un contrôle parfait sur un flux que personne ne comprend — et alors la seule chose que tu peux faire avec précision, c'est l'éteindre.
La fiche minimale : une page par flux, huit champs
Si la fiche ne tient pas sur une page, elle ne sera pas entretenue. C'est tout le critère de conception. Huit champs, des réponses de deux lignes, et c'est fini :
- Ce qu'il produit. La sortie concrète, pas la catégorie. « Ajoute une ligne par commande dans la feuille logistique », pas « gère les commandes ».
- Propriétaire. Une personne. Si le nom qui figure là ne travaille plus ici, la fiche est périmée et ça se voit d'un coup d'œil.
- Règle métier. Le pourquoi de chaque condition, avec son origine. C'est le champ long et le seul qui justifie l'existence de la fiche.
- Exceptions. Quel cas rare couvre chaque branche et quel incident l'a mise là.
- Qui il alerte. Personne ou file, canal, délai, et ce qui se passe si personne ne répond.
- Identifiants. Quel compte il utilise, à qui il appartient et avec quels droits. Aucun secret dans la fiche, évidemment : juste le nom du compte.
- Systèmes qu'il touche. Ce qu'il lit et ce qu'il écrit, en deux listes séparées.
- Ce qu'il ne fait PAS. La limite explicite du flux.
Le huitième champ est celui que personne ne met et celui qui évite le plus de disputes. « Ne touche pas aux factures déjà émises », « n'écrit pas dans l'ERP », « ne répond pas en dehors des horaires ». Sans ce champ, chaque incident commence par vingt minutes à écarter l'hypothèse que ce soit ce flux — et au bout d'un an, tout le monde lui prête des pouvoirs qu'il n'a jamais eus.
Où doit vivre la fiche pour ne pas vieillir
Voilà la partie gênante, et je la dis sans détour : si la fiche vit dans un Confluence, un Notion ou un dossier Drive à part, elle vieillira. Ce n'est pas la faute de l'outil, c'est la distance. Celui qui modifie le flux est dans l'éditeur, pressé, en train de réparer quelque chose ; si mettre la fiche à jour veut dire ouvrir un autre onglet, chercher la page et éditer, il ne le fera pas. Une fois, ce n'est rien. Au dixième changement, la fiche ment.
La fiche doit vivre là où vit le flux. Trois endroits qui marchent vraiment, du moins au plus d'effort : le champ description ou les notes du scénario lui-même —Make, n8n, Power Automate et presque tous en ont un—, là où la friction est la plus faible parce que tu es déjà dedans ; un README à côté du JSON exporté si tu versionnes tes flux dans un dépôt, ce qui t'offre en prime l'historique des modifications ; et une note épinglée dans le canal où le flux publie, quand sa sortie est une notification.
Le wiki ne disparaît pas : il change de rôle. Il cesse d'être l'endroit où vit la documentation et devient l'index —quels flux existent, qui est le propriétaire de chacun et où se trouve sa fiche—. Ça, ça tient, parce que c'est une liste courte qui bouge peu. Ce qui ne tient pas, c'est le détail loin de l'endroit où on y touche.
Mettre la fiche à jour fait partie du changement, ce n'est pas une tâche à part
Toute documentation qui meurt meurt de la même façon : quelqu'un l'écrit dans un effort ponctuel et, à partir de là, l'entretenir devient « une tâche » qui entre en concurrence avec le vrai travail. Elle entre en concurrence et elle perd, à chaque fois, parce que ce n'est jamais urgent et que personne ne l'attend.
La seule façon d'éviter ça, c'est de la sortir de la liste de tâches et de la mettre dans la définition de terminé. Modifier un flux n'est pas terminé quand le flux marche : c'est terminé quand le flux marche et que sa fiche dit ce qu'il fait maintenant. Deux minutes si la fiche est à un clic, et deux minutes qui n'existent que si personne ne les traite comme optionnelles. Le reste —rappels trimestriels, campagnes de documentation, audits internes— c'est du théâtre avec un calendrier.
C'est ça qui boucle la boucle avec le reste du cluster. Un flux avec une fiche et un propriétaire est un flux qu'on peut maintenir en vie sans deviner, et un flux qui ne finit pas en automatisation zombie que personne n'éteint parce que personne ne sait ce qui casse. Documenter ne maintient ni ne retire : ça transforme maintenir et retirer en décisions plutôt qu'en paris. Si tu montes tout ça depuis zéro, la carte complète est dans le guide pour automatiser avec l'IA.