Il mito della documentazione che nessuno scrive

Chiedete a qualsiasi responsabile di progetto IT se la documentazione è importante. La risposta sarà sempre un convinto “Assolutamente sì”. Poi chiedete di vedere quella documentazione. Il silenzio che seguirà dirà più di mille parole.

La documentazione software vive in uno strano limbo tra ciò che dovrebbe esistere e ciò che effettivamente esiste. Viene menzionata in ogni piano di progetto, allocata nei budget, discussa nelle riunioni. Eppure, quando serve davvero, si scopre che è incompleta, obsoleta, o semplicemente inesistente.

L’illusione del grande manuale

Esiste una fantasia ricorrente nel mondo IT: il Grande Manuale Definitivo. Un’opera enciclopedica che descrive ogni aspetto del sistema, ogni decisione progettuale, ogni riga di codice. Un tomo che risponde a tutte le domande e risolve tutti i dubbi.

Questa visione è tanto seducente quanto irrealistica. Creare un documento del genere richiede un investimento di tempo colossale, sottraendo risorse preziose allo sviluppo vero e proprio. Ma il problema principale non è nemmeno il tempo necessario per crearlo.

Il problema è che diventa obsoleto quasi istantaneamente. Una piccola modifica al codice, un refactoring minore, un aggiustamento dell’architettura, e improvvisamente intere sezioni del manuale diventano non solo inutili, ma potenzialmente fuorvianti. Chi mantiene aggiornato questo leviatano documentale? La risposta è quasi sempre: nessuno.

I progetti ambiziosi di documentazione enciclopedica seguono un pattern prevedibile. Si parte con grande entusiasmo, allocando ore e risorse. Si creano template elaborati, si definiscono standard rigorosi, si pianificano sessioni di scrittura. Poi arriva la prima scadenza critica, e la documentazione viene rimandata. Poi arriva la seconda, e la terza. Alla fine, il Grande Manuale rimane un’idea nell’aria, sostituito da qualche slide affrettata presentata alla chiusura del progetto.

Il principio della documentazione efficace

La documentazione che funziona segue un principio semplice: concentrarsi sul 20% che genera l’80% del valore. Non serve documentare ogni dettaglio, serve documentare le decisioni architetturali critiche, le parti non intuitive del sistema, i pattern ricorrenti, le trappole nascoste.

Un buon documento di architettura di dieci pagine vale più di un manuale di trecento pagine che nessuno leggerà mai. La domanda non è “quanto possiamo scrivere?” ma “cosa serve davvero a chi dovrà lavorare su questo sistema?”

Eppure, questa saggezza viene sistematicamente ignorata. I responsabili di progetto continuano a pianificare documentazione monumentale, gli sviluppatori continuano a promettere che “la faremo nella prossima fase”, e tutti sanno che non succederà.

Quando arriva un nuovo sviluppatore

Il vero test della documentazione arriva quando un nuovo membro si unisce al team. La domanda è sempre la stessa: “Dove posso trovare la documentazione del sistema?”

In un’organizzazione ideale, la risposta sarebbe un link a una wiki ben strutturata, con diagrammi aggiornati e guide chiare. Nella realtà, la risposta più comune è un silenzio imbarazzato, seguito da “Ti spiego io a voce” o “Guarda il codice, è abbastanza chiaro”.

In alcuni casi, la “documentazione” consiste in tre rettangoli disegnati su una lavagna, collegati da frecce, con la spiegazione “Questo è il sistema, se hai domande chiedi”. Non è uno scherzo, è la realtà quotidiana di molti progetti.

Il nuovo arrivato impara quindi per osmosi, facendo domande ripetute agli sviluppatori senior, che custodiscono la conoscenza del sistema nelle loro teste. Questo crea una dinamica perversa: chi conosce il sistema diventa indispensabile, e quindi ha scarso incentivo a documentare quella conoscenza in modo che altri possano apprenderla.

Il versionamento come problema sconosciuto

Un fenomeno curioso è l’incapacità di applicare alla documentazione le stesse pratiche di versionamento usate per il codice. Mentre il codice viene gestito con repository, branch, merge e tag, la documentazione vive in un caos di file chiamati “NUOVA_VERSIONE_DEFINITIVA_2_ULTIMA.doc”.

In progetti con decine di sviluppatori che usano quotidianamente strumenti di version control, la documentazione viene ancora gestita inviando file via email con oggetto “Sostituisce la versione precedente”, senza mai specificare quale sia quella precedente né preoccuparsi di rimuovere le versioni superate.

Il risultato è un labirinto di documenti quasi identici, dove trovare la versione corretta richiede un dottorato in archeologia documentale. Esistono vent’anni di strumenti per gestire questo problema, eppure continuiamo a comportarci come se fossimo ancora nell’era pre-digitale.

I due mondi della documentazione

La documentazione si divide tipicamente in due categorie: quella tecnica per gli sviluppatori e quella per gli utenti finali. Entrambe condividono un destino comune di negligenza, ma in modi diversi.

La documentazione tecnica, quando esiste, viene abbandonata alla prima modifica architetturale significativa. Il documento che descrive l’architettura del sistema diventa rapidamente un reperto storico, che racconta com’era il sistema tre versioni fa, non come è oggi.

Il manuale utente ha un problema diverso: contiene screenshot di interfacce che non esistono più da due release, descrive funzionalità che sono state spostate o eliminate, e ignora completamente le nuove caratteristiche aggiunte negli ultimi sei mesi. È un documento di fantascienza, che descrive un prodotto alternativo in un universo parallelo.

I piani di test fantasma

I piani di test meritano una menzione speciale nell’olimpo della documentazione mancante. Questi documenti mitologici dovrebbero garantire la qualità del software, ma nella pratica sono più rari degli avvistamenti UFO.

Quando esistono, mostrano una caratteristica peculiare: sono dettagliatissimi sulle funzionalità semplici e vaghi su quelle complesse. Trentadue casi di test per la schermata di login, ma solo una descrizione generica per il processo di elaborazione che è il cuore del sistema.

Si trovano casi di test del tipo “Verificare che il sistema funzioni correttamente” o “Testare tutte le funzionalità principali”. Indicazioni così utili quanto “Per costruire una casa, assemblare i materiali in modo appropriato”.

L’autogenerazione come salvezza illusoria

La tentazione di risolvere il problema con l’automazione è forte. Strumenti che generano documentazione dai commenti nel codice, sistemi che creano diagrammi dalle dipendenze, intelligenze artificiali che promettono di scrivere manuali perfetti.

Il problema è che l’automazione può solo trasformare l’input fornito. Se i commenti nel codice sono del tipo “Fix this later” o “Non toccare questo o esplode tutto”, la documentazione auto-generata sarà altrettanto inutile. Spazzatura in input, spazzatura documentata in output.

Ore vengono spese a configurare questi strumenti, scrivere plugin personalizzati, tutto per poter dire “La documentazione si aggiorna da sola!” Il risultato è un documento che esiste tecnicamente, ma che nessuno consulta perché non contiene le informazioni realmente utili.

Il paradosso del valore

Eppure, nei rari casi in cui esiste documentazione ben fatta e mantenuta, i benefici sono evidenti. Nuovi sviluppatori diventano produttivi in giorni invece che settimane. I bug vengono risolti in ore invece che giorni. Le decisioni tecniche vengono prese con cognizione di causa invece che per tentativi.

La buona documentazione è come un buon arbitro: se non ti accorgi che esiste, sta probabilmente facendo un ottimo lavoro. Non è un ostacolo né un peso, ma uno strumento che semplifica la vita a tutti. È aggiornata quando serve, accessibile quando necessaria, chiara quando consultata.

Ma questi casi rimangono eccezioni. La norma è il ciclo infinito di promesse non mantenute, dove ogni progetto parte con l’intenzione di “fare le cose per bene questa volta” e finisce con le solite slide affrettate e la consueta assenza di documentazione utilizzabile.

Il codice come documentazione

C’è chi sostiene che il codice ben scritto sia esso stesso documentazione sufficiente. Ed è vero, fino a un certo punto. Nomi di variabili descrittivi, funzioni con responsabilità chiare, struttura logica evidente: tutto questo riduce la necessità di spiegazioni aggiuntive.

Ma il codice racconta il “come”, raramente il “perché”. Non spiega le decisioni architetturali, i vincoli del business, i requisiti che hanno guidato certe scelte. Non documenta le alternative considerate e scartate, le lezioni apprese, i problemi già risolti che potrebbero ripresentarsi.

Il codice perfetto rimane una forma di documentazione incompleta. Necessaria, ma non sufficiente.

La verità scomoda

La verità è che continuiamo a promettere documentazione sapendo che non la faremo. Perché quando arriva il momento, c’è sempre qualcosa di più urgente: una deadline impossibile, un cliente esigente, un bug critico in produzione.

La documentazione viene sempre pianificata nei progetti, sempre discussa nelle riunioni, sempre rimandata a dopo. E quel “dopo” non arriva mai. Rimangono le slide con i rettangoli colorati, i diagrammi approssimativi, e la conoscenza tribale tramandata oralmente da una generazione di sviluppatori all’altra.

La prossima volta che qualcuno nel team dice “dovremmo documentare meglio”, tutti annuiranno con convinzione. Prometteranno che questa volta sarà diverso. E poi continueranno esattamente come prima, perché la prima regola del club della documentazione è: tutti parlano dell’importanza della documentazione, ma nessuno la scrive davvero.

Questo articolo è tratto da “Non funziona niente! – I progetti IT in crisi”, il primo libro della collana Nothing Works! — una tragicommedia aziendale per chi ha visto troppi Gantt chart trasformarsi in fiction.

Scopri la collana completa, gli altri libri e le prossime uscite su nothingworks.it

Vuoi il libro subito? Compralo su Amazon

Potrebbe interessarti anche

• Sistemista IT in una PMI: mansioni e competenze
• DIRETTORE ACQUISTI
• Perché documentare gli interventi IT potenzia la posizione del Sistemista?
• BACK OFFICE MANAGER
• Da sistemista IT a IT Manager: un, possibile, percorso di carriera nell’ambito manifatturiero
• SOC MANAGER 
• I problemi quotidiani di un Sistemista IT e come risolverli
• SISTEMISTA
• Quanto guadagna un Sistemista a Torino?
• SISTEMISTA IT