Documentare i clic non serve: quelli li salva già lo strumento
Quando qualcuno cerca come documentare le automazioni, finisce quasi sempre per fare la stessa cosa: screenshot dell'editor, un passo-passo di quale modulo viene dopo quale e una descrizione di ogni nodo. Un pomeriggio intero di lavoro. Ed è lavoro buttato, perché stai ricopiando a mano l'unica cosa che lo strumento sa già da solo.
Make, n8n, Zapier o Power Automate ti mostrano il grafo del flusso in due clic: cosa lo attiva, cosa viene dopo, quale campo si mappa con quale. Quello è vivo e sempre aggiornato. Il tuo screenshot no: scade la prima volta che il produttore sposta un menu o cambia il colore di un pulsante, e da lì in poi documenta un'interfaccia che non esiste più.
L'effetto collaterale è peggio del disallineamento. Una documentazione che sembra vecchia smette di essere letta, e appena smette di essere letta tutti danno per scontato che anche il resto menta. Un manuale che nessuno apre è esattamente utile quanto non avere manuale, con la differenza che va pure mantenuto.
Il grafo ti dice cosa fa il flusso. Non ti dice mai perché. E il perché non sta da nessuna parte tranne che nella testa di chi l'ha costruito.
Il bus factor: se solo una testa sa il perché, quello è il tuo rischio vero
Il bus factor di un sistema è quante persone se ne possono andare prima che quel sistema resti senza nessuno in grado di capirlo. Nell'automazione aziendale il numero è quasi sempre uno. Una persona ha costruito il flusso, quella persona sa perché la soglia è 48 ore e non 72, e quella persona è quella che si chiama quando succede qualcosa di strano.
Non serve un autobus. Bastano una vacanza, un cambio di team, un'assenza lunga o un'offerta migliore. E la parte scomoda è che il flusso non si rompe —quello sarebbe facile da vedere—: continua a girare puntualmente tutti i giorni. Quello che si rompe è la capacità di cambiarlo.
Si vede molto prima che arrivi il disastro. I sintomi di un bus factor uguale a uno sono sempre gli stessi cinque:
- Nessuno tocca il flusso. Le modifiche si attaccano da fuori, in un flusso nuovo, perché modificare l'originale fa paura.
- Ogni cambio di business apre una discussione archeologica. «Ma questo perché sta così?». Nessuno lo sa, quindi si lascia com'è.
- Spunta un duplicato. Qualcuno costruisce un altro flusso che fa quasi la stessa cosa, perché ripartire da zero costava meno che capire quello che c'era.
- Non si riesce a spiegare una decisione. Arriva la domanda di un cliente o di un revisore sul perché il sistema abbia fatto quello che ha fatto, e la risposta onesta è che non si sa.
- Il flusso si congela. Quando la persona se ne va, resta acceso e nessuno osa né cambiarlo né spegnerlo.
Nota che nessuno di questi cinque sintomi si cura con uno screenshot dell'editor.
L'unica cosa da scrivere: la regola di business
Una regola di business è la decisione umana che il flusso prende a tuo nome mentre nessuno guarda. Non è «se il campo stato è uguale a in attesa, invia email». È: «al cliente che non risponde da 48 ore mandiamo un sollecito, perché il contratto tipo promette risposta entro due giorni lavorativi e non vogliamo violarlo; salvo che sia un cliente grande, e allora viene avvisato l'account invece del sistema».
Tutto il resto —il modulo, l'ordine, la mappatura dei campi— è implementazione. Cambia il giorno in cui cambi strumento e non succede niente. La regola sopravvive allo strumento: se domani migri da Zapier a n8n, la regola è l'unica cosa che devi portarti dietro, ed è precisamente l'unica che non è scritta da nessuna parte.
Perché quella condizione e non un'altra
Ogni numero che compare in un flusso è uscito da qualche parte: un impegno di servizio, una promessa commerciale, un requisito legale o —il caso più frequente— una riunione di due anni fa. Scrivi quale. «48 ore perché è il termine che promette il contratto tipo» è una condizione rivedibile il giorno in cui il contratto cambia. Un «48 ore» secco è un numero intoccabile che nessuno oserà mai spostare.
Quale eccezione copre
I rami strani di un flusso non sono quasi mai un capriccio: sono cicatrici. Quel filtro che scarta gli ordini sotto un certo importo sta lì perché un giorno è passata una tornata di test e ha sporcato la fatturazione. Scrivere la cicatrice evita le due cose che succedono quando non è scritta: che qualcuno tolga il filtro per «pulizia» e l'incidente torni, o che nessuno osi toccarlo anche se il motivo originale è sparito da anni.
Chi avvisa e cosa succede se nessuno risponde
Quello che salta in produzione di solito non è la logica: è il finale aperto. Un flusso che scala a una persona deve dire a chi, su quale canale, entro quale termine — e cosa fa se quella persona non risponde. Se la risposta è «resta in attesa a tempo indeterminato», anche quella è una decisione e va scritta, perché il giorno in cui un ordine resta fermo una settimana qualcuno chiederà se è un guasto o il progetto.
Attaccati alla regola vanno tre dati che non sono business ma si perdono con la stessa facilità: il proprietario —una persona con nome e cognome, non un reparto—, le credenziali che usa —quale account, di chi, con quali permessi— e i sistemi che tocca, separando quello che legge da quello che scrive. Quello che scrive è ciò che ti può scompaginare il CRM un martedì pomeriggio.
Qui questa guida sfiora la governance e il controllo dell'automazione senza essere la stessa cosa. La governance mette permessi, audit e freno a mano: è controllo. Questa è conoscenza. Puoi avere un controllo perfetto su un flusso che nessuno capisce — e allora l'unica cosa che puoi fare con precisione è spegnerlo.
La scheda minima: una pagina per flusso, otto campi
Se la scheda non sta in una pagina, non verrà mantenuta. È tutto qui il criterio di progetto. Otto campi, risposte di due righe, e finita:
- Cosa produce. L'output concreto, non la categoria. «Aggiunge una riga per ordine nel foglio della logistica», non «gestisce gli ordini».
- Proprietario. Una persona. Se il nome che compare non lavora più qui, la scheda è scaduta e si vede a colpo d'occhio.
- Regola di business. Il perché di ogni condizione, con la sua origine. È il campo lungo e l'unico che giustifica l'esistenza della scheda.
- Eccezioni. Quale caso raro copre ogni ramo e quale incidente ce l'ha messo.
- Chi avvisa. Persona o coda, canale, termine, e cosa succede se nessuno risponde.
- Credenziali. Quale account usa, di chi è e con quali permessi. Nessun segreto dentro la scheda, ovviamente: solo il nome dell'account.
- Sistemi che tocca. Cosa legge e cosa scrive, in due liste separate.
- Cosa NON fa. Il limite esplicito del flusso.
L'ottavo campo è quello che nessuno mette ed è quello che risparmia più discussioni. «Non tocca le fatture già emesse», «non scrive nell'ERP», «non risponde fuori orario». Senza quel campo ogni incidente comincia con venti minuti per escludere che sia stato questo flusso — e passato un anno, tutti gli attribuiscono poteri che non ha mai avuto.
Dove deve vivere la scheda per non invecchiare
Ecco la parte scomoda, e la dico senza giri: se la scheda vive in un Confluence, un Notion o una cartella Drive a parte, invecchierà. Non è colpa dello strumento, è la distanza. Chi cambia il flusso è dentro l'editor, di corsa, mentre sistema qualcosa; se aggiornare la scheda significa aprire un'altra pagina, cercarla e modificarla, non lo farà. Una volta non succede niente. Al decimo cambio, la scheda mente.
La scheda deve vivere dove vive il flusso. Tre posti che funzionano davvero, dal meno al più faticoso: il campo descrizione o le note dello scenario stesso —ce l'hanno Make, n8n, Power Automate e quasi tutti—, dove l'attrito è minimo perché sei già dentro; un README accanto al JSON esportato se versioni i flussi in un repository, che ti regala anche lo storico delle modifiche; e una nota fissata nel canale dove il flusso pubblica, quando il suo output è una notifica.
Il wiki non sparisce: cambia ruolo. Smette di essere il posto dove vive la documentazione e diventa l'indice —quali flussi esistono, chi è il proprietario di ciascuno e dove sta la sua scheda—. Quello regge, perché è una lista corta che cambia poco. Quello che non regge è il dettaglio lontano dal posto in cui lo si tocca.
Aggiornare la scheda fa parte del cambio, non è un compito a parte
Tutta la documentazione che muore muore allo stesso modo: qualcuno la scrive in uno sforzo una tantum e, da lì in poi, mantenerla è «un compito» che compete con il lavoro vero. Compete e perde, sempre, perché non è mai urgente e nessuno la sta aspettando.
L'unico modo perché non succeda è tirarla fuori dalla lista dei compiti e metterla dentro la definizione di fatto. Cambiare un flusso non è finito quando il flusso funziona: è finito quando il flusso funziona e la sua scheda dice cosa fa adesso. Sono due minuti se la scheda è a un clic, e sono due minuti che esistono solo se nessuno li tratta come opzionali. Il resto —promemoria trimestrali, campagne di documentazione, audit interni— è teatro con il calendario.
È così che si chiude il cerchio con il resto del cluster. Un flusso con scheda e con proprietario è un flusso che si può mantenere vivo senza indovinare niente, ed è un flusso che non finisce per diventare una di quelle automazioni zombie che nessuno spegne perché nessuno sa cosa si rompe. Documentare non mantiene e non ritira: fa sì che mantenere e ritirare siano decisioni invece che scommesse. Se stai costruendo tutto questo da zero, la mappa completa è nella guida per automatizzare con l'IA.