Procedura scritta e procedura eseguibile: esempio prima/dopo

Avere una procedura non significa poterla eseguire. “Aggiornare il servizio, controllare che funzioni, avvisare il team” descrive un'intenzione. Non spiega quale servizio, quali controlli o cosa fare se il risultato è diverso da quello previsto.

Una procedura eseguibile riduce la necessità di indovinare. Non elimina il giudizio tecnico: rende esplicito dove quel giudizio serve e chi può esercitarlo.

Prima: una nota che funziona solo per l'autore

Consideriamo questa istruzione dimostrativa:

Fare il deploy della nuova versione.
Controllare i log.
Se ci sono problemi tornare indietro.
Avvisare gli utenti.

Chi l'ha scritta probabilmente conosce ambiente, accessi e dipendenze. Un sostituto deve invece ricostruire tutto. “Tornare indietro” può essere pericoloso se la nuova versione ha modificato il database.

La nota non è inutile: è un buon indice dei passaggi da approfondire. Il problema nasce quando viene trattata come una procedura già pronta per la produzione.

Dopo: una struttura operativa

Una versione migliore parte dai confini:

Scopo: rilasciare una versione approvata del servizio indicato nella change.
Responsabile: referente del rilascio nominato nella change.
Prerequisiti: versione identificata, test superati, finestra approvata,
              accessi autorizzati, strategia dati e recovery verificata.
Stop iniziale: non procedere se manca uno dei prerequisiti.
Controllo finale: health check e operazione applicativa concordata.
Chiusura: registrare esito, versione attiva e validazione del referente.

Questa è ancora una struttura da adattare, non un comando universale di deploy. La procedura reale deve indicare pipeline, ambiente, verifica della versione e punti di controllo specifici.

Scrivi “azione, attesa, deviazione”

Per ogni passo indica cosa fare, cosa dovrebbe accadere e quale percorso seguire se non accade. Esempio: avviare la pipeline approvata; attendere il risultato del job; in caso di errore non rilanciarla alla cieca, ma conservare l'identificativo e seguire l'escalation.

Il controllo applicativo deve essere significativo: una pagina che risponde non dimostra che un ordine venga salvato correttamente. Scegli con il referente un'operazione di prova reversibile e autorizzata, senza alterare dati reali inutilmente.

Il rientro va progettato insieme ai dati

Un artefatto precedente può non essere compatibile con una migrazione già applicata. Per questo la strategia può essere rollback dell'applicazione, fix forward o recovery: la scelta dipende dall'ambiente e deve essere verificata prima della finestra.

Definisci chi decide, quali segnali impongono lo stop e quale tempo rimane per il recupero. La procedura non deve suggerire operazioni irreversibili come risposta automatica a un errore generico.

Una prova che rivela i punti deboli

Chiedi a una seconda persona autorizzata di seguire il documento in un ambiente di test. Ogni domanda che richiede la presenza dell'autore evidenzia una lacuna: un link mancante, una soglia non definita o un permesso non disponibile.

Registra le ambiguità invece di aggiungere pagine senza criterio. Spesso bastano un risultato atteso e una condizione di stop per chiarire un passo difficile.

Quando la procedura è pronta?

Quando ha un responsabile, un contesto dichiarato, accessi gestiti, controlli verificabili e una prova completata. Aggiungi versione, ultima revisione e condizioni che richiedono aggiornamento: cambiamento della pipeline, dipendenze nuove o modifica dei permessi.

La prova non garantisce che non ci saranno errori. Dimostra però che il documento è stato usato da qualcuno diverso dall'autore e che le principali decisioni non sono rimaste implicite.

Hai una nota operativa che funziona soltanto per chi l'ha scritta? Scopri Procedure Sprint 30: possiamo partire da un esempio e trasformarlo in una procedura provabile, invece di produrre documentazione destinata a restare ferma.